diff --git a/.claude/skills/pair-capability-assess-cost/SKILL.md b/.claude/skills/pair-capability-assess-cost/SKILL.md new file mode 100644 index 00000000..6a05b68d --- /dev/null +++ b/.claude/skills/pair-capability-assess-cost/SKILL.md @@ -0,0 +1,132 @@ +--- +name: pair-capability-assess-cost +description: "Classifies the financial exposure of a change as a chromatic cost class (green/yellow/orange/red) at review or on demand, by scanning the diff/story for cost signals against the KB cost-signal catalog resolved through the project's stack/architecture/infrastructure adoption. Output-only: emits the cost dimension of the classification matrix (1-line verdict + collapsed details, D22) for /pair-capability-classify and /pair-process-review to consume — writes nothing, blocks nothing. Multi-provider by construction: adding a provider touches adoption/KB only, never this skill." +version: 0.1.0 +author: Foomakers +--- + +# /pair-capability-assess-cost — Cost Assessment + +Classify the financial exposure of a change as a chromatic **cost class** (`green` / `yellow` / `orange` / `red`) from the cost signals present in the diff (or, at refinement, the story scope), against a rule set resolved from the [quality model](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) (§2 Cost pillar, §3.3 Cost class) plus the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) — the single home of the cost-signal catalog, the general + provider-specific heuristics (AWS first), and the cost gotchas. + +**Output-only.** This skill emits the cost dimension of the classification matrix and nothing else: it **writes no files, creates no backlog items, and never blocks** a PR or merge (it has no such authority — the merge decision stays with `/pair-process-review`, exactly as the `assess-security` sibling reports a verdict but never blocks). The cost class it computes is consumed by `/pair-capability-classify` and `/pair-process-review`; the skill never interprets or acts on its own verdict. + +**Provider-agnostic core (R2.13).** No provider names are hardcoded in this skill. Which heuristics apply is selected by the project's `tech-stack.md` / `architecture.md` / `infrastructure.md` adoption files (Q3); the catalog and per-provider heuristics live in the guideline (D17/D21). Adding a provider is an adoption/KB change (a new per-provider section or an adoption link), never a change to this skill. + +## Arguments + +| Argument | Required | Description | +| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `$diff` | No | The PR/branch diff to classify. Default when invoked by `/pair-process-review` or against a branch: the current diff. | +| `$story` | No | A story/issue to classify from its declared scope instead of a diff — the refinement-time (shift-left) path, mirroring the risk matrix built twice. | +| `$scope` | No | Area/package to scope the scan (default: the whole diff/story). Package-scoped only — never narrows the rule set, only the surface scanned. | + +`$diff` and `$story` are mutually exclusive inputs; exactly one surface is classified per run. Neither provided → auto-detect: a PR/diff in context (i.e. invoked by `/pair-process-review`) → `$diff`; a story in context (i.e. invoked by `/pair-process-refine-story`/`/pair-capability-classify` in refinement) → `$story`. + +## Rule Set + +Every rule resolves through the standard **Argument > Adoption > KB default** cascade of the quality model (§quality-model.md resolution order): + +1. **KB default** — [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) §3.3 (class = highest detected signal; class token `cost:green|yellow|orange|red`) + the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) (the signal catalog, the general heuristics, the per-provider heuristics starting with AWS, the gotchas). +2. **Provider selection (adoption)** — read `tech-stack.md`, `architecture.md`, `infrastructure.md`: the declared cloud/provider (e.g. AWS) selects which per-provider heuristics in the guideline apply. A provider the guideline does not cover in-tree is reached via an **adoption link** the adoption file supplies (fallback/extension — no skill change, Q3). +3. **Project delta (adoption)** — `tech/risk-matrix.md` `## Overrides` may tune cost thresholds (e.g. reclassify a shared path); absent ⇒ KB defaults apply completely (D21). + +A missing/malformed adoption file is treated as absent: warn and fall back to KB defaults (D21) — never HALT on adoption absence. + +## Algorithm + +### Step 0: Load the Quality Model (BLOCKING prerequisite) + +1. **Check**: Does [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) resolve (KB installed)? +2. **Act**: If it is **missing**, **HALT** — the quality model is a prerequisite, not a default this skill can invent. Report: _"Quality model not found — install/bootstrap the KB (`quality-model.md` §3.3) before running assess-cost."_ +3. **Verify**: The Cost class section (§3.3) and the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) are loaded. + +### Step 1: Resolve the Rule Set + +1. **Act**: Read the KB default (§3.3 + cost-assessment guideline), then the adoption files (Rule Set layers 2–3), skipping any that don't exist. +2. **Act**: Select the applicable per-provider heuristics from the declared stack/infrastructure (e.g. AWS); for a provider only reachable via an adoption link, resolve that link. +3. **Verify**: Effective catalog + heuristics assembled. Adoption absence is logged as "KB defaults only", not an error. + +### Step 2: Resolve the Surface + +1. **Act**: Determine the surface: `$diff` (touched files/hunks) or `$story` (declared scope — infra/service load the story introduces), narrowed by `$scope` if given. +2. **Verify**: A concrete surface (file set or story scope) is resolved. + +### Step 3: Scan for Cost Signals + +1. **Act**: Scan the surface against the cost-signal catalog (maintained in the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md)) — e.g. paid-SDK imports (payment/LLM/messaging providers), API-key env vars, IaC/provisioning changes, cron/scheduled jobs, queues/pipelines, media processing, LLM calls. For each hit, record the signal, its location, and the class it maps to per the guideline's heuristics (general + the selected provider's). +2. **Act**: **Unresolvable cost surface** (unknown tech whose cost profile the catalog + adoption cannot resolve): record it as an **unknown-surface** hit and assign it **orange** — the conservative, visible middle-high, never silently green (edge case: "unknown surface" flag). +3. **Verify**: Every touched cost-relevant surface has a signal, a location, and a mapped class; unknown surfaces are flagged, not dropped. + +### Step 4: Compute the Class + +1. **Act**: **Cost class = the highest detected signal** across all hits (§3.3). **No signal detected ⇒ `green`** with rationale _"no cost surface touched"_ (AC4). +2. **Act**: In refinement (`$story`) the class is the shift-left, declared value; in review (`$diff`) it is the observed value — carried in the same compiled matrix as its own class (never folded into the risk `max`, §3.2), tag token `cost:green|yellow|orange|red`. +3. **Verify**: Exactly one class computed, with a 1-line rationale and the detected-signals list. + +### Step 5: Emit the Verdict + +1. **Act**: Render the 1-line class + rationale and the collapsed `
` signals table per Output Format below — **output-only, no files written**. This is embedded by the caller into the classification matrix's cost dimension (D22 — verdict in ~1 line, details in `
`), consumed by `/pair-capability-classify` and shown by `/pair-process-review`. +2. **Verify**: Verdict emitted. A `red` (or flagged unknown-surface) class is reported for the caller's attention; the skill itself blocks nothing — the merge decision stays `/pair-process-review`'s. + +## Output Format + +```text +COST ASSESSMENT (output-only — no files written): +├── Class: [green | yellow | orange | red] — [1-line rationale] +├── Surface: [diff | story #ID | scope ] +├── Signals: [N detected — N unknown-surface] +├── Rule Set: [KB default | + provider | + adoption tech/risk-matrix.md] +└── Feeds: Cost dimension of the classification matrix (quality-model §3.3) — own class, not part of the risk max + +
+N cost signals + +| Signal | Location | Class | Notes | +| ------ | -------- | ----- | ----- | +| [signal] | [file:location] | [green|yellow|orange|red] | [provider heuristic / unknown-surface] | +... + +
+``` + +No signal detected renders as: `Class: green — no cost surface touched` with an empty (or omitted) signals table. + +## Composition Interface + +When composed by `/pair-process-review` (review-time cost dimension): + +- **Input**: the reviewing skill invokes `/pair-capability-assess-cost` against the PR diff (`$diff`). +- **Output**: returns the class + collapsed signals (Output Format above). The caller embeds it into the review report's cost section (1 line + `
`, D22) and feeds the class into `/pair-capability-classify`'s cost dimension. +- **Persistence**: none — this skill writes nothing. + +When composed by `/pair-process-refine-story` / `/pair-capability-classify` (shift-left, refinement): + +- Classifies from `$story` scope, producing the declared cost class carried in the story-body matrix — the review pass may only confirm-or-raise it, never lower it (D17 "built twice": the class is estimated from story context at refinement and re-derived from the diff at review — the more conservative of the two wins). + +When invoked **independently** (`/pair-capability-assess-cost` on a branch or story): full one-shot classification, verdict returned to the developer. + +> Review-side wiring (listing `/pair-capability-assess-cost` as a Composed Skill in `/pair-process-review` and adding the cost section to the review template) is delivered separately (#228). This skill is authored ready-to-compose; nothing here depends on that wiring existing yet. + +## Edge Cases + +- **No cost-relevant change** (AC4): class `green`, rationale "no cost surface touched". +- **Unresolvable cost surface** (unknown tech): class `orange` with an explicit **unknown-surface** flag — conservative and visible, never silently green (Step 3.2). +- **Quality model missing**: **HALT** with a pointer to install/bootstrap the KB (Step 0) — the model is a prerequisite, not something this skill invents. +- **Provider not covered in-tree**: resolved via the adoption link the adoption file supplies (fallback/extension) — no skill change (Q3). +- **Adoption file missing/malformed**: warn, fall back to KB defaults (D21) — never a HALT. + +## Graceful Degradation + +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: + +- **cost-assessment guideline absent** (KB partially installed): assess against quality-model §3.3's inline signal list only, and note the reduced catalog in the output rather than HALTing. +- **`/pair-capability-classify` not available** (independent invocation): the class is still emitted; it simply isn't folded into a compiled matrix by a caller — the developer reads the verdict directly. + +## Notes + +- **Writes nothing** — the strict output-only convention of the assess-* family (unlike `assess-security`, this skill has no report/audit mode: report/monitoring is deliberately split to a separate slice). The class is data for `/pair-capability-classify`/`/pair-process-review`, never an action this skill takes. +- **Never blocks** — no merge authority; a `red` class is a signal for the caller, not a gate this skill enforces. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. +- **Provider-agnostic** — adding a provider is an adoption/KB change (a per-provider section in the guideline, or an adoption link), never a change to this skill (R2.13). +- **D22** (1-line verdict + collapsed details): a project-level rendering decision the caller honors; this skill emits in that shape. diff --git a/.claude/skills/pair-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index 6948bce4..0759b2f0 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /pair-next — Project Navigator -Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 38-skill catalog across all lifecycle phases. +Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 39-skill catalog across all lifecycle phases. ## Arguments (optional) @@ -37,9 +37,9 @@ Keep only candidate issues that carry the given label. `--filter` takes a **sing The scope is **stateless across steps**. Every run — and every step of a multi-step run — re-queries the PM tool and **re-evaluates** `--root` and `--filter` against the **current** board state. If an issue's tags change between steps (e.g. a review raises `risk:yellow` → `risk:red`), the next step's selection reflects the change immediately. `/pair-next` never reuses a selection computed in a previous step. -## Skill Catalog (38 skills) +## Skill Catalog (39 skills) -The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 28 capability + `/pair-next` itself = 38. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. +The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 29 capability + `/pair-next` itself = 39. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. ### Process Skills (9) @@ -55,7 +55,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde | `/pair-process-implement` | Sprint Execution | Implement story tasks with TDD | | `/pair-process-review` | Sprint Execution | Review PR through structured phases | -### Capability Skills (28) +### Capability Skills (29) | Skill | Category | Description | | ------------------------ | --------------- | ---------------------------------------------------------------------------- | @@ -80,6 +80,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde | `/pair-capability-assess-infrastructure` | Assessment | Assess infrastructure strategy | | `/pair-capability-assess-observability` | Assessment | Assess observability strategy | | `/pair-capability-assess-security` | Assessment | Assess security posture (review verdict + one-shot audit) | +| `/pair-capability-assess-cost` | Assessment | Classify cost exposure (green/yellow/orange/red) at review — output-only | | `/pair-capability-analyze-debt` | Analysis | Analyze technical debt with prioritization | | `/pair-capability-analyze-code-quality` | Analysis | Analyze code quality with metrics | | `/pair-capability-estimate` | Planning | Estimate story using adopted methodology | @@ -113,12 +114,12 @@ Read the following files and classify each as **populated** or **template**: | File | Template indicator | | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| [.pair/adoption/product/PRD.md](../../../.pair/adoption/product/PRD.md) | Contains `[Product/feature name]` or `[Creation date]` | -| [.pair/adoption/product/subdomain/README.md](../../../.pair/adoption/product/subdomain/README.md) | Contains `[list here core subdomain]` or `[PROJECT_NAME]` | -| [.pair/adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) | Contains only placeholder headings with no real content | -| [.pair/adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) | Contains only placeholder headings with no real content | -| [.pair/adoption/tech/boundedcontext/README.md](../../../.pair/adoption/tech/boundedcontext/README.md) | Contains only placeholder headings with no real content | -| [.pair/adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) | No PM tool specified or only template text | +| [.pair/adoption/product/PRD.md](../../.pair/adoption/product/PRD.md) | Contains `[Product/feature name]` or `[Creation date]` | +| [.pair/adoption/product/subdomain/README.md](../../.pair/adoption/product/subdomain/README.md) | Contains `[list here core subdomain]` or `[PROJECT_NAME]` | +| [.pair/adoption/tech/architecture.md](../../.pair/adoption/tech/architecture.md) | Contains only placeholder headings with no real content | +| [.pair/adoption/tech/tech-stack.md](../../.pair/adoption/tech/tech-stack.md) | Contains only placeholder headings with no real content | +| [.pair/adoption/tech/boundedcontext/README.md](../../.pair/adoption/tech/boundedcontext/README.md) | Contains only placeholder headings with no real content | +| [.pair/adoption/tech/way-of-working.md](../../.pair/adoption/tech/way-of-working.md) | No PM tool specified or only template text | **Template detection rule**: A file is a template if it contains square-bracket placeholders (e.g., `[Product/feature name]`) or if its substantive sections contain no project-specific content. @@ -143,9 +144,9 @@ All adoption files are populated. Query the PM tool to determine backlog state Rows 12–15 are likewise project-wide and not surfaced under a scope; when the candidate set yields no actionable item, Step 0 item 5's clean exit governs (see Step 0). -**PM tool discovery**: Read [.pair/adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) to identify the PM tool (GitHub Projects, Jira, Linear, etc.) and access method. +**PM tool discovery**: Read [.pair/adoption/tech/way-of-working.md](../../.pair/adoption/tech/way-of-working.md) to identify the PM tool (GitHub Projects, Jira, Linear, etc.) and access method. -**State resolution**: The conditions below refer to canonical **macrostates** (`Draft`, `Ready`, `In Progress`, `Review`, `Done`), never board-specific labels. Resolve each item's board state to a macrostate via the `## State Mapping` section in way-of-working.md — omitted ⇒ canonical names are assumed. See [canonical-states.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md) for the full resolution rule. When a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback: evaluate the [Definition of Ready criteria](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md) against the item instead of guessing from the board-state name. +**State resolution**: The conditions below refer to canonical **macrostates** (`Draft`, `Ready`, `In Progress`, `Review`, `Done`), never board-specific labels. Resolve each item's board state to a macrostate via the `## State Mapping` section in way-of-working.md — omitted ⇒ canonical names are assumed. See [canonical-states.md](../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md) for the full resolution rule. When a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback: evaluate the [Definition of Ready criteria](../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md) against the item instead of guessing from the board-state name. | # | Condition | Suggestion | Rationale | | --- | ---------------------------------------------------------------- | ------------------- | ------------------------------------------- | @@ -205,16 +206,16 @@ Then ask: "Shall I run `/skill-name`?" ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → skip Step 3, recommend from adoption files only; adoption files missing → suggest `/pair-process-bootstrap` as the entry point) for the standard scenarios. Additional cases: +See [graceful degradation](../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → skip Step 3, recommend from adoption files only; adoption files missing → suggest `/pair-process-bootstrap` as the entry point) for the standard scenarios. Additional cases: - **Argument edge cases** (see Step 0): `--root` not found → HALT, no action; `--root` resolves to a Done issue → report and exit; `--filter` (or the subtree) matches nothing → report `no matching issues` and exit cleanly (an empty result is not an error). - If a suggested skill is not installed, tell the user which skill is needed and where to find it. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. -- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback ([Definition of Ready criteria](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md)) rather than treating row 11's condition as unresolvable. +- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback ([Definition of Ready criteria](../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md)) rather than treating row 11's condition as unresolvable. ## Notes - This skill is read-only: it inspects state but never modifies files or PM tool data. - Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/pair-next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: nearly all of the 38 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/pair-capability-checkpoint`, rows 12-16 including `/pair-capability-grill`) or process-skill composition. `/pair-capability-publish-pr` will be reachable via `/pair-process-implement` once wired (not yet composed), so `/next` cannot surface it today. +- **Full catalog coverage**: nearly all of the 39 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/pair-capability-checkpoint`, rows 12-16 including `/pair-capability-grill`) or process-skill composition. `/pair-capability-publish-pr` will be reachable via `/pair-process-implement` once wired (not yet composed), so `/pair-next` cannot surface it today. diff --git a/.pair/knowledge/getting-started.md b/.pair/knowledge/getting-started.md index 7b0285a4..7195715f 100644 --- a/.pair/knowledge/getting-started.md +++ b/.pair/knowledge/getting-started.md @@ -79,7 +79,7 @@ Welcome to the AI-Human pairing repository template! This guide provides essenti - **`way-of-working.md`**: Main process documentation – the starting point to understand the full workflow - **`getting-started.md`**: This guide – essential information to get started with the framework -- **`skills-guide.md`**: Full catalog of 38 Agent Skills (9 process + 28 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions +- **`skills-guide.md`**: Full catalog of 39 Agent Skills (9 process + 29 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions - **`how-to/`**: Step-by-step guides for each development phase and LLM collaboration - Process guides (01-11): Operational documentation for each phase - **`assets/`**: Templates, checklists, and document examples (e.g., PRD, bootstrap checklist) diff --git a/.pair/knowledge/guidelines/quality-assurance/README.md b/.pair/knowledge/guidelines/quality-assurance/README.md index ea9d5664..748a799d 100644 --- a/.pair/knowledge/guidelines/quality-assurance/README.md +++ b/.pair/knowledge/guidelines/quality-assurance/README.md @@ -25,6 +25,7 @@ This comprehensive quality assurance framework ensures systematic quality manage ### **Core Quality Framework** - **quality-model.md** - Single source of default quality rules: 3-layer principle, 3 pillars (Cost/Security/Delivery), classification dimensions and tier resolution, per-tier review/gate requirements, tag projection, `tech/risk-matrix.md` adoption delta schema, nested taxonomy +- **cost-assessment.md** - Cost pillar guideline: the cost-signal catalog, general + provider-specific heuristics (AWS first, other providers via adoption links), and cost gotchas; applied by `assess-cost` (quality-model §3.3) - **automated-verification.md** - Comprehensive automated verification system for tool-based validation and quality gate enforcement - **manual-verification.md** - Manual verification processes and human-driven quality assessment methodologies - **manual-testing.md** - Guidelines for designing, organizing, and executing manual test suites for post-release validation diff --git a/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md b/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md new file mode 100644 index 00000000..c4405dc3 --- /dev/null +++ b/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md @@ -0,0 +1,83 @@ +# Cost Assessment + +The single home of the **cost-signal catalog** and the cost-classification heuristics the `assess-cost` skill applies. This is the Cost pillar's guideline in the [quality model](quality-model.md) (§2 Cost pillar, §3.3 Cost class): the model owns the *class scale and the resolution cascade*; this document owns the *signals and heuristics*. Nothing here duplicates the quality model — it fills in the "which signals, at what class" the model forward-references. + +**Layering.** The `assess-cost` skill applies these rules; it holds none of them itself (D17/D21). Provider selection is adoption-driven (`tech-stack.md` / `architecture.md` / `infrastructure.md`): the declared provider selects the per-provider section below; a provider not covered in-tree is reached through an **adoption link** the adoption file supplies (fallback/extension — no skill or KB-core change). Deeper cost-optimization strategy for running systems lives in [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md); this document is about *classifying a change at review*, not tuning a bill. + +## Class scale + +Cost class is chromatic, four levels, matching the quality model's tag token `cost:green|yellow|orange|red` (§3.3): + +| Class | Meaning | Typical trigger | +| --- | --- | --- | +| 🟢 `green` | No cost surface touched | no catalog signal detected | +| 🟡 `yellow` | Low, bounded, predictable exposure | a single low-cost signal on a non-critical path | +| 🟠 `orange` | Material or unclear exposure | scaling/usage-driven signal, or an **unknown cost surface** (conservative default) | +| 🔴 `red` | High/open-ended exposure | provisioning that can grow without a ceiling (e.g. always-on compute, per-token LLM at scale, unbounded fan-out) | + +**Class = the highest detected signal** across the scanned surface (§3.3). No signal ⇒ `green` ("no cost surface touched"). An **unknown cost surface** (tech whose cost profile the catalog + adoption cannot resolve) is classified `orange` and flagged — conservative and visible, never silently green. + +## Cost-signal catalog + +Scanned on the diff (or, at refinement, the story's declared scope). Each signal maps to a **baseline class**; a per-provider heuristic (below) or an adoption override may raise it. Highest hit wins. + +| Signal | What to look for | Baseline class | +| --- | --- | --- | +| **paid-SDK imports** | new dependency on a paid/metered provider SDK — payment (Stripe, etc.), LLM (OpenAI/Anthropic/etc.), messaging/email/SMS (Twilio/SendGrid/etc.) | 🟠 orange (per-use billing) | +| **API-key env vars** | new secret/env var naming a paid service (`*_API_KEY`, `*_SECRET`, provider tokens) | 🟡 yellow (paid integration surface) | +| **IaC / provisioning changes** | Terraform/CloudFormation/CDK/Pulumi/SST resources, `*.tf`, serverless configs — anything that stands up billable infrastructure | 🟠 orange (🔴 red if it provisions always-on/unbounded resources) | +| **cron / scheduled jobs** | new scheduled task, cron expression, scheduled workflow | 🟡 yellow (🟠 orange if frequent/heavy) | +| **queues / pipelines** | new queue, stream, pub/sub topic, data pipeline, event bus | 🟠 orange (throughput-driven) | +| **media processing** | image/video/audio transcode, thumbnailing, OCR, large-file processing | 🟠 orange (CPU/egress heavy) | +| **LLM calls** | inference calls, embeddings, per-token/per-request model usage | 🟠 orange (🔴 red at scale / per-request on a hot path) | +| **storage / egress growth** | new bucket/table with unbounded growth, high-egress paths, CDN origins | 🟡 yellow (🟠 orange if unbounded) | +| **always-on compute** | new long-running service, container, or instance that runs 24/7 | 🔴 red (fixed recurring floor) | + +The catalog is intentionally provider-neutral: a signal is detected the same way regardless of cloud. The **provider heuristics** below refine a signal's class where a specific provider's pricing shape matters. + +## General cost heuristics + +- **Fixed vs. usage-driven**: a fixed recurring cost (always-on compute, reserved capacity) is a floor that never goes to zero — treat as at least 🟠 orange, 🔴 red if sizeable. Usage-driven cost (per-request, per-token, per-GB) is bounded by traffic — its class rises with the expected volume and the criticality of the path it sits on. +- **Bounded vs. unbounded**: a ceiling (rate limit, max instances, quota) caps exposure — one class lower than the same signal without a ceiling. Unbounded fan-out, autoscaling with no max, or recursive processing → 🔴 red. +- **Hot-path multiplier**: the same signal on a high-traffic/critical path is one class higher than on a cold/admin path. +- **New vs. reused**: reusing an already-provisioned resource is lower than standing up a new one; only the *incremental* exposure of the change is classified. + +## AWS-specific heuristics + +Applied when the adoption declares AWS (`infrastructure.md` / `tech-stack.md`). See also [infrastructure/cloud-providers/aws-deployment.md](../infrastructure/cloud-providers/aws-deployment.md) and [cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). + +| AWS surface | Cost shape | Class guidance | +| --- | --- | --- | +| Lambda | per-request + duration; scales to zero | 🟡 yellow bounded; 🟠 orange on a hot path or with high memory/duration | +| EC2 / ECS on EC2 / RDS instances | always-on hourly floor | 🔴 red (fixed recurring), 🟠 orange only for the smallest/dev tiers | +| Fargate | per-task vCPU/memory-seconds | 🟠 orange; 🔴 red for always-on long-running tasks | +| S3 | cheap storage, **egress + request cost is the trap** | 🟡 yellow storage; 🟠 orange for high-egress/high-request paths | +| DynamoDB | on-demand (usage) vs. provisioned (floor) | 🟡 yellow on-demand bounded; 🟠 orange provisioned or GSIs | +| SQS / SNS / Kinesis / EventBridge | per-message/per-shard throughput | 🟠 orange (throughput-driven); Kinesis shards are a floor → 🔴 red if many | +| NAT Gateway | hourly floor **+ per-GB data processing** | 🔴 red — a classic silent bill (see gotchas) | +| CloudFront / data transfer out | per-GB egress | 🟠 orange, scales with traffic | +| Bedrock / SageMaker | per-token / per-inference / endpoint hours | 🟠 orange per-token; 🔴 red for always-on endpoints | + +## Other providers + +Provider coverage is **adoption-extensible**: a project on GCP, Azure, Vercel, Cloudflare, etc. supplies an **adoption link** (in `infrastructure.md` / `tech-stack.md`) to the provider's cost model or a project-local cost note; `assess-cost` resolves that link as the per-provider heuristic layer. No change to this KB core or to the skill is needed to add a provider — that is the multi-provider contract (R2.13). The general heuristics above always apply as the provider-neutral floor. Baseline provider evaluation guidance: [infrastructure/cloud-providers/provider-evaluation.md](../infrastructure/cloud-providers/provider-evaluation.md) and [multi-cloud.md](../infrastructure/cloud-providers/multi-cloud.md). + +## Cost gotchas + +Non-obvious patterns that read as cheap but bill like they are not — classify these conservatively (at least 🟠 orange): + +- **NAT Gateway data-processing charges** — the hourly rate is small; the per-GB processing on every byte to the internet is the real bill. +- **S3/CloudFront egress**, not storage — storage is pennies; data transfer out is where the money goes. +- **CloudWatch Logs / high-cardinality metrics** — verbose logging or per-request custom metrics can outgrow the compute they observe. +- **DynamoDB GSIs** — each global secondary index is a full second copy of write throughput and storage. +- **Kinesis / provisioned shards** — a floor cost per shard whether or not data flows. +- **Cross-AZ / cross-region traffic** — inter-AZ data transfer is billed and easy to introduce accidentally. +- **LLM context bloat** — per-token pricing makes large prompts/long context windows scale cost linearly with every call; retries and agent loops multiply it. +- **"Serverless" that never sleeps** — a scheduled job or warmer keeping a function hot removes the scale-to-zero benefit. +- **Free-tier cliffs** — a signal that is free at low volume can jump a class once past the free tier; classify by expected steady-state volume, not the demo. + +## Relationship to the quality model + +- The **class scale** and the **resolution cascade** (Argument > Adoption > KB default) are owned by [quality-model.md](quality-model.md) §3.3 — not restated here. +- This guideline owns the **catalog** and the **heuristics**; `assess-cost` is the skill that applies them (three-layer principle, §1 of the quality model). +- Cost is its **own class**, never folded into the risk `max` (§3.2); it is projected as the `cost:*` tag only if a project opts in via `tech/risk-matrix.md`'s Tag Projection (§5). diff --git a/.pair/knowledge/guidelines/quality-assurance/quality-model.md b/.pair/knowledge/guidelines/quality-assurance/quality-model.md index 0d17924a..f01c49f6 100644 --- a/.pair/knowledge/guidelines/quality-assurance/quality-model.md +++ b/.pair/knowledge/guidelines/quality-assurance/quality-model.md @@ -18,7 +18,7 @@ The single source of default quality rules for this KB. `classify`, `assess-cost | Pillar | Covers | Tag family (if exposed) | Primary skill | | --- | --- | --- | --- | -| **Cost** | Financial exposure of building/running the change | `cost:*` — opt-in, §5 | `assess-cost` (cost-signal catalog, forthcoming) | +| **Cost** | Financial exposure of building/running the change | `cost:*` — opt-in, §5 | `assess-cost` (cost-signal catalog) | | **Security** | Vulnerabilities, compliance, secure-by-design | none dedicated — feeds `risk:*` (§3) + deterministic CI scanning | `assess-security`, [security/](security/README.md) | | **Delivery** | Everything else: correctness, performance, a11y, observability, docs, planning, architecture, release, AI metrics | `risk:*` (correctness/blast-radius facets) — KB default, §5 | `pair-process-review`, `classify` | @@ -52,7 +52,7 @@ Coupling sources absent (no subdomain/bounded-context artifacts, no `assess-coup ### 3.3 Cost class (R6.2) -Cost class = **highest detected signal**. The signal catalog (paid-SDK imports, API-key env vars, IaC/provisioning changes, cron/queues, media processing, LLM calls) is maintained in the cost-assessment guideline (forthcoming, `assess-cost`); no signal detected ⇒ `green`. General + provider-specific heuristics: [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). This value is always computed and written to the story/PR body's matrix (§1); it is projected as the `cost:green|yellow|orange|red` tag only if a project adds `cost` to its Tag Projection declaration (§5) — the KB does not do this by default. +Cost class = **highest detected signal**. The signal catalog (paid-SDK imports, API-key env vars, IaC/provisioning changes, cron/queues, media processing, LLM calls) is maintained in the [cost-assessment guideline](cost-assessment.md), applied by `assess-cost`; no signal detected ⇒ `green`. General + provider-specific heuristics (AWS first, other providers via adoption links) live there too; deeper running-cost optimization is in [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). This value is always computed and written to the story/PR body's matrix (§1); it is projected as the `cost:green|yellow|orange|red` tag only if a project adds `cost` to its Tag Projection declaration (§5) — the KB does not do this by default. ## 4. Per-Tier Requirements @@ -166,4 +166,4 @@ Every quality theme not covered by §1–§6 lives under one of the three pillar | Release | Delivery | [../technical-standards/deployment-workflow/release-management.md](../technical-standards/deployment-workflow/release-management.md) | | AI metrics / retro | Delivery | [../collaboration/project-tracking/README.md](../collaboration/project-tracking/README.md) (reports land in `.pair/working/reports/`, once available) | | Vulnerabilities / compliance | Security | [security/vulnerability-prevention.md](security/vulnerability-prevention.md), [security/compliance.md](security/compliance.md) | -| Cost signals | Cost | cost-assessment guideline (not yet published, see §3.3) | +| Cost signals | Cost | [cost-assessment.md](cost-assessment.md) (see §3.3) | diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index 74c985b9..ceef1aba 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/pair-next` at the start of every session. It reads project adoption files | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 28 | Atomic units — perform a single focused operation | +| **Capability** | 29 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 38 (9 process + 28 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 39 (9 process + 29 capability + 1 navigator). ## Full Catalog @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) were removed — domain modeling is referenced inline by each real caller's own how-to (02, 03, 06, 09; 08 planned — #242). See [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (28) +### Capability Skills (29) #### Domain Modeling Skills (2) @@ -48,7 +48,7 @@ Process skills compose capability skills. Capability skills are independently in Reclassified from process to capability (D24) — see [Callers Matrix](#callers-matrix-scoped-capabilities) and [Migration Notes](#migration-notes). -#### Assessment Skills (9) +#### Assessment Skills (10) | Skill | Scope | |-------|-------| @@ -61,6 +61,7 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/pair-capability-assess-observability` | Observability strategy evaluation | | `/pair-capability-assess-ai` | AI development tools evaluation | | `/pair-capability-assess-security` | Security posture — review verdict (`$mode: review`, composed by `/pair-process-review`) + one-shot OWASP Top 10 audit (`$mode: audit`). Unlike the 8 above, not purely output-only — writes its own audit report (D14 exception); never scans for secrets, that's the deterministic CI layer `/pair-capability-setup-gates` provisions (D24) | +| `/pair-capability-assess-cost` | Cost exposure — chromatic class (`cost:green\|yellow\|orange\|red`) from the diff/story against the [cost-signal catalog](guidelines/quality-assurance/cost-assessment.md) (general + AWS-first, other providers via adoption links). Output-only: feeds `/pair-capability-classify`'s cost dimension, writes nothing, blocks nothing; report/monitoring mode is a separate slice | #### Classification Skills (1) diff --git a/.pair/knowledge/way-of-working.md b/.pair/knowledge/way-of-working.md index b0822622..3cecd041 100644 --- a/.pair/knowledge/way-of-working.md +++ b/.pair/knowledge/way-of-working.md @@ -78,4 +78,4 @@ The process is designed to: 2. **🤖🤝👨‍💻 Code Review** (`/pair-process-review`) → Structured review with adoption compliance, merge flow, and parent cascade 3. **🤖⚡ Status Update** → Automatic story/epic/initiative tracking update (handled by `/pair-process-implement` and `/pair-process-review`) -> **Skill-enabled workflow**: Run `/pair-next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 38 skills. +> **Skill-enabled workflow**: Run `/pair-next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 39 skills. diff --git a/.pair/llms.txt b/.pair/llms.txt index 0917fbed..fb03dccb 100644 --- a/.pair/llms.txt +++ b/.pair/llms.txt @@ -259,6 +259,7 @@ - [Accessibility Validation Workflow Framework](.pair/knowledge/guidelines/quality-assurance/accessibility/validation-workflow.md) - [WCAG Compliance Implementation](.pair/knowledge/guidelines/quality-assurance/accessibility/wcag-compliance.md) - [Automated Verification Framework](.pair/knowledge/guidelines/quality-assurance/automated-verification.md) +- [Cost Assessment](.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) - [Manual Testing Guidelines](.pair/knowledge/guidelines/quality-assurance/manual-testing.md) - [Manual Verification Framework](.pair/knowledge/guidelines/quality-assurance/manual-verification.md) - [Performance Benchmarking Framework](.pair/knowledge/guidelines/quality-assurance/performance/benchmarking.md) diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 71096eea..4f79611c 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -285,5 +285,5 @@ Three distinct verbs, kept separate — don't overload one across branches: **`v - [Agent Skills specification](https://agentskills.io) — The open standard, including frontmatter fields and size limits. - [`writing-great-skills`](https://github.com/mattpocock/skills) — The reference model behind the effectiveness standard (predictability, information hierarchy, leading words, pruning). -- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 38 pair skills. +- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 39 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. diff --git a/apps/website/content/docs/developer-journey/execution.mdx b/apps/website/content/docs/developer-journey/execution.mdx index ef8fae36..93dcbacb 100644 --- a/apps/website/content/docs/developer-journey/execution.mdx +++ b/apps/website/content/docs/developer-journey/execution.mdx @@ -120,6 +120,6 @@ This loop repeats for every story. `/pair-next` always knows what comes next. ## Reference -- [Skills Catalog](/docs/reference/skills-catalog) — all 38 skills with commands and composition +- [Skills Catalog](/docs/reference/skills-catalog) — all 39 skills with commands and composition - [Guidelines & How-To Catalog](/docs/reference/guidelines-catalog) — all 9 guideline categories and 9 how-to guides - [Adopt a Knowledge Base](/docs/customization/adopt) — set up pair if you haven't already diff --git a/apps/website/content/docs/developer-journey/index.mdx b/apps/website/content/docs/developer-journey/index.mdx index 83129829..7cfd95fc 100644 --- a/apps/website/content/docs/developer-journey/index.mdx +++ b/apps/website/content/docs/developer-journey/index.mdx @@ -40,7 +40,7 @@ Level 4: Execution (per story) You can follow this flow in two ways: -1. **Process Skills (recommended)** — invoke a slash command and the AI handles the structured process for you. See the [Skills Catalog](/docs/reference/skills-catalog) for all 38 skills. +1. **Process Skills (recommended)** — invoke a slash command and the AI handles the structured process for you. See the [Skills Catalog](/docs/reference/skills-catalog) for all 39 skills. 2. **How-to Guides** — follow the manual step-by-step instructions from the Knowledge Base. See the [Guidelines & How-To Catalog](/docs/reference/guidelines-catalog) for all 9 how-to guides. Skills compose capability skills internally, enforce adoption compliance, and update your PM tool automatically. The how-to guides give you the same process with full manual control. @@ -117,5 +117,5 @@ Feeling lost? Check the [FAQ](/docs/support/general-faq) — it answers common q ## Reference -- [Skills Catalog](/docs/reference/skills-catalog) — all 38 skills with commands and composition +- [Skills Catalog](/docs/reference/skills-catalog) — all 39 skills with commands and composition - [Guidelines & How-To Catalog](/docs/reference/guidelines-catalog) — all 9 guideline categories and 9 how-to guides diff --git a/apps/website/content/docs/getting-started/index.mdx b/apps/website/content/docs/getting-started/index.mdx index 15ce8907..fc49a125 100644 --- a/apps/website/content/docs/getting-started/index.mdx +++ b/apps/website/content/docs/getting-started/index.mdx @@ -15,7 +15,7 @@ A structured set of documents — guidelines, how-tos, architecture decisions, t ## Skills -Structured instructions that AI assistants discover and execute, following the [Agent Skills](https://agentskills.io) open standard. Skills automate the full product lifecycle — from PRD creation to code review — with 38 composable skills covering process and capability concerns. +Structured instructions that AI assistants discover and execute, following the [Agent Skills](https://agentskills.io) open standard. Skills automate the full product lifecycle — from PRD creation to code review — with 39 composable skills covering process and capability concerns. [Learn more about Skills](/docs/concepts/skills) diff --git a/apps/website/content/docs/integrations/claude-code.mdx b/apps/website/content/docs/integrations/claude-code.mdx index fcc9ffff..932aea3a 100644 --- a/apps/website/content/docs/integrations/claude-code.mdx +++ b/apps/website/content/docs/integrations/claude-code.mdx @@ -25,7 +25,7 @@ your-project/ │ ├── pair-next/ │ ├── pair-process-implement/ │ ├── pair-capability-verify-quality/ -│ └── ... ← 38 skills +│ └── ... ← 39 skills ├── .pair/ │ ├── knowledge/ ← upstream guidelines (don't edit) │ └── adoption/ ← your project decisions diff --git a/apps/website/content/docs/reference/guidelines-catalog.mdx b/apps/website/content/docs/reference/guidelines-catalog.mdx index a76a7495..9e0521cf 100644 --- a/apps/website/content/docs/reference/guidelines-catalog.mdx +++ b/apps/website/content/docs/reference/guidelines-catalog.mdx @@ -157,7 +157,7 @@ Design systems, research, and content strategy. ## Related - [Quality Model](/docs/reference/quality-model) — the single source of default quality rules (classification, tiers, tags) -- [Skills Catalog](/docs/reference/skills-catalog) — all 38 pair skills with commands and composition +- [Skills Catalog](/docs/reference/skills-catalog) — all 39 pair skills with commands and composition - [Process Lifecycle](/docs/developer-journey) — step-by-step walkthrough of the full process - [KB Structure](/docs/reference/kb-structure) — directory layout and file purposes - [Customize for Your Team](/docs/customization/team) — override guidelines via adoption files diff --git a/apps/website/content/docs/reference/kb-structure.mdx b/apps/website/content/docs/reference/kb-structure.mdx index 8a6aa4ca..fbb280dc 100644 --- a/apps/website/content/docs/reference/kb-structure.mdx +++ b/apps/website/content/docs/reference/kb-structure.mdx @@ -121,7 +121,7 @@ Neither subdirectory is scaffolded by `pair install` — a skill creates them on - [Customize the Knowledge Base](/docs/customization/team) — How to override guidelines - [Configuration Reference](/docs/reference/configuration) — config.json options -- [Skills Catalog](/docs/reference/skills-catalog) — All 38 pair skills +- [Skills Catalog](/docs/reference/skills-catalog) — All 39 pair skills - [llms.txt](/docs/concepts/llms-txt) — How pair makes docs and project context consumable by AI assistants - [knowledge-hub README](https://github.com/foomakers/pair/blob/main/packages/knowledge-hub/README.md) — KB package operations, scripts, and maintainer guide - [content-ops README](https://github.com/foomakers/pair/blob/main/packages/content-ops/README.md) — File operations API, copy behaviors, and transform configuration diff --git a/apps/website/content/docs/reference/skill-management.mdx b/apps/website/content/docs/reference/skill-management.mdx index a5e656d0..eacddd57 100644 --- a/apps/website/content/docs/reference/skill-management.mdx +++ b/apps/website/content/docs/reference/skill-management.mdx @@ -267,6 +267,6 @@ No code change is required in `apps/pair-cli` — the `skills` registry (`config ## Related -- [Skills Catalog](/docs/reference/skills-catalog) — All 38 pair skills +- [Skills Catalog](/docs/reference/skills-catalog) — All 39 pair skills - [Configuration Reference](/docs/reference/configuration) — config.json registry settings - [KB Structure Reference](/docs/reference/kb-structure) — Directory layout diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index 7911167a..71858904 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/apps/website/content/docs/reference/skills-catalog.mdx @@ -1,9 +1,9 @@ --- title: Skills Catalog -description: Complete catalog of all 38 pair skills organized by type — process, capability, and meta. +description: Complete catalog of all 39 pair skills organized by type — process, capability, and meta. --- -pair ships with 38 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant. +pair ships with 39 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant. > **Last updated:** 2026-07-19. Source: `packages/knowledge-hub/dataset/.skills/` @@ -50,6 +50,7 @@ All `assess-*` skills are **output-only**: they produce a proposal (rendered ado | ----- | ------- | ----------- | | **assess-ai** | `/pair-capability-assess-ai` | Evaluates and recommends AI development tools — coding assistants, agent frameworks, MCP integrations, models — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | | **assess-architecture** | `/pair-capability-assess-architecture` | Evaluates and recommends an architecture pattern (layered, hexagonal, microservices, etc.) when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-cost** | `/pair-capability-assess-cost` | Assesses cost class (green/yellow/orange/red) against the multi-provider cost-signal catalog — composed by `/pair-process-review` to feed the classification matrix's cost dimension. Output-only, never blocks. | | **assess-infrastructure** | `/pair-capability-assess-infrastructure` | Evaluates and recommends infrastructure strategy — cloud, CI/CD, deployment, IaC, environments — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | | **assess-methodology** | `/pair-capability-assess-methodology` | Evaluates and recommends the development methodology (Scrum, Kanban, Lean, etc.) — iterations, ceremonies, flow — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | | **assess-observability** | `/pair-capability-assess-observability` | Evaluates and recommends the observability strategy — monitoring, logging, tracing, alerting, telemetry — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | diff --git a/apps/website/lib/docs-staleness-check.test.ts b/apps/website/lib/docs-staleness-check.test.ts index 2e0fba2a..8966462e 100644 --- a/apps/website/lib/docs-staleness-check.test.ts +++ b/apps/website/lib/docs-staleness-check.test.ts @@ -169,9 +169,9 @@ describe('buildValidRoutes', () => { }) describe('runAllChecks (in-process, real docs tree)', () => { - it('reports zero drift and 38 skills against the actual repo', () => { + it('reports zero drift and 39 skills against the actual repo', () => { const { errors, skillCount } = runAllChecks(REPO_ROOT) expect(errors, errors.join('\n')).toHaveLength(0) - expect(skillCount).toBe(38) + expect(skillCount).toBe(39) }) }) diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md b/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md index 829881b3..309bd8e7 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md @@ -79,7 +79,7 @@ Welcome to the AI-Human pairing repository template! This guide provides essenti - **`way-of-working.md`**: Main process documentation – the starting point to understand the full workflow - **`getting-started.md`**: This guide – essential information to get started with the framework -- **`skills-guide.md`**: Full catalog of 38 Agent Skills (9 process + 28 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions +- **`skills-guide.md`**: Full catalog of 39 Agent Skills (9 process + 29 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions - **`how-to/`**: Step-by-step guides for each development phase and LLM collaboration - Process guides (01-11): Operational documentation for each phase - **`assets/`**: Templates, checklists, and document examples (e.g., PRD, bootstrap checklist) diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/README.md index ea9d5664..748a799d 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/README.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/README.md @@ -25,6 +25,7 @@ This comprehensive quality assurance framework ensures systematic quality manage ### **Core Quality Framework** - **quality-model.md** - Single source of default quality rules: 3-layer principle, 3 pillars (Cost/Security/Delivery), classification dimensions and tier resolution, per-tier review/gate requirements, tag projection, `tech/risk-matrix.md` adoption delta schema, nested taxonomy +- **cost-assessment.md** - Cost pillar guideline: the cost-signal catalog, general + provider-specific heuristics (AWS first, other providers via adoption links), and cost gotchas; applied by `assess-cost` (quality-model §3.3) - **automated-verification.md** - Comprehensive automated verification system for tool-based validation and quality gate enforcement - **manual-verification.md** - Manual verification processes and human-driven quality assessment methodologies - **manual-testing.md** - Guidelines for designing, organizing, and executing manual test suites for post-release validation diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md new file mode 100644 index 00000000..c4405dc3 --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/cost-assessment.md @@ -0,0 +1,83 @@ +# Cost Assessment + +The single home of the **cost-signal catalog** and the cost-classification heuristics the `assess-cost` skill applies. This is the Cost pillar's guideline in the [quality model](quality-model.md) (§2 Cost pillar, §3.3 Cost class): the model owns the *class scale and the resolution cascade*; this document owns the *signals and heuristics*. Nothing here duplicates the quality model — it fills in the "which signals, at what class" the model forward-references. + +**Layering.** The `assess-cost` skill applies these rules; it holds none of them itself (D17/D21). Provider selection is adoption-driven (`tech-stack.md` / `architecture.md` / `infrastructure.md`): the declared provider selects the per-provider section below; a provider not covered in-tree is reached through an **adoption link** the adoption file supplies (fallback/extension — no skill or KB-core change). Deeper cost-optimization strategy for running systems lives in [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md); this document is about *classifying a change at review*, not tuning a bill. + +## Class scale + +Cost class is chromatic, four levels, matching the quality model's tag token `cost:green|yellow|orange|red` (§3.3): + +| Class | Meaning | Typical trigger | +| --- | --- | --- | +| 🟢 `green` | No cost surface touched | no catalog signal detected | +| 🟡 `yellow` | Low, bounded, predictable exposure | a single low-cost signal on a non-critical path | +| 🟠 `orange` | Material or unclear exposure | scaling/usage-driven signal, or an **unknown cost surface** (conservative default) | +| 🔴 `red` | High/open-ended exposure | provisioning that can grow without a ceiling (e.g. always-on compute, per-token LLM at scale, unbounded fan-out) | + +**Class = the highest detected signal** across the scanned surface (§3.3). No signal ⇒ `green` ("no cost surface touched"). An **unknown cost surface** (tech whose cost profile the catalog + adoption cannot resolve) is classified `orange` and flagged — conservative and visible, never silently green. + +## Cost-signal catalog + +Scanned on the diff (or, at refinement, the story's declared scope). Each signal maps to a **baseline class**; a per-provider heuristic (below) or an adoption override may raise it. Highest hit wins. + +| Signal | What to look for | Baseline class | +| --- | --- | --- | +| **paid-SDK imports** | new dependency on a paid/metered provider SDK — payment (Stripe, etc.), LLM (OpenAI/Anthropic/etc.), messaging/email/SMS (Twilio/SendGrid/etc.) | 🟠 orange (per-use billing) | +| **API-key env vars** | new secret/env var naming a paid service (`*_API_KEY`, `*_SECRET`, provider tokens) | 🟡 yellow (paid integration surface) | +| **IaC / provisioning changes** | Terraform/CloudFormation/CDK/Pulumi/SST resources, `*.tf`, serverless configs — anything that stands up billable infrastructure | 🟠 orange (🔴 red if it provisions always-on/unbounded resources) | +| **cron / scheduled jobs** | new scheduled task, cron expression, scheduled workflow | 🟡 yellow (🟠 orange if frequent/heavy) | +| **queues / pipelines** | new queue, stream, pub/sub topic, data pipeline, event bus | 🟠 orange (throughput-driven) | +| **media processing** | image/video/audio transcode, thumbnailing, OCR, large-file processing | 🟠 orange (CPU/egress heavy) | +| **LLM calls** | inference calls, embeddings, per-token/per-request model usage | 🟠 orange (🔴 red at scale / per-request on a hot path) | +| **storage / egress growth** | new bucket/table with unbounded growth, high-egress paths, CDN origins | 🟡 yellow (🟠 orange if unbounded) | +| **always-on compute** | new long-running service, container, or instance that runs 24/7 | 🔴 red (fixed recurring floor) | + +The catalog is intentionally provider-neutral: a signal is detected the same way regardless of cloud. The **provider heuristics** below refine a signal's class where a specific provider's pricing shape matters. + +## General cost heuristics + +- **Fixed vs. usage-driven**: a fixed recurring cost (always-on compute, reserved capacity) is a floor that never goes to zero — treat as at least 🟠 orange, 🔴 red if sizeable. Usage-driven cost (per-request, per-token, per-GB) is bounded by traffic — its class rises with the expected volume and the criticality of the path it sits on. +- **Bounded vs. unbounded**: a ceiling (rate limit, max instances, quota) caps exposure — one class lower than the same signal without a ceiling. Unbounded fan-out, autoscaling with no max, or recursive processing → 🔴 red. +- **Hot-path multiplier**: the same signal on a high-traffic/critical path is one class higher than on a cold/admin path. +- **New vs. reused**: reusing an already-provisioned resource is lower than standing up a new one; only the *incremental* exposure of the change is classified. + +## AWS-specific heuristics + +Applied when the adoption declares AWS (`infrastructure.md` / `tech-stack.md`). See also [infrastructure/cloud-providers/aws-deployment.md](../infrastructure/cloud-providers/aws-deployment.md) and [cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). + +| AWS surface | Cost shape | Class guidance | +| --- | --- | --- | +| Lambda | per-request + duration; scales to zero | 🟡 yellow bounded; 🟠 orange on a hot path or with high memory/duration | +| EC2 / ECS on EC2 / RDS instances | always-on hourly floor | 🔴 red (fixed recurring), 🟠 orange only for the smallest/dev tiers | +| Fargate | per-task vCPU/memory-seconds | 🟠 orange; 🔴 red for always-on long-running tasks | +| S3 | cheap storage, **egress + request cost is the trap** | 🟡 yellow storage; 🟠 orange for high-egress/high-request paths | +| DynamoDB | on-demand (usage) vs. provisioned (floor) | 🟡 yellow on-demand bounded; 🟠 orange provisioned or GSIs | +| SQS / SNS / Kinesis / EventBridge | per-message/per-shard throughput | 🟠 orange (throughput-driven); Kinesis shards are a floor → 🔴 red if many | +| NAT Gateway | hourly floor **+ per-GB data processing** | 🔴 red — a classic silent bill (see gotchas) | +| CloudFront / data transfer out | per-GB egress | 🟠 orange, scales with traffic | +| Bedrock / SageMaker | per-token / per-inference / endpoint hours | 🟠 orange per-token; 🔴 red for always-on endpoints | + +## Other providers + +Provider coverage is **adoption-extensible**: a project on GCP, Azure, Vercel, Cloudflare, etc. supplies an **adoption link** (in `infrastructure.md` / `tech-stack.md`) to the provider's cost model or a project-local cost note; `assess-cost` resolves that link as the per-provider heuristic layer. No change to this KB core or to the skill is needed to add a provider — that is the multi-provider contract (R2.13). The general heuristics above always apply as the provider-neutral floor. Baseline provider evaluation guidance: [infrastructure/cloud-providers/provider-evaluation.md](../infrastructure/cloud-providers/provider-evaluation.md) and [multi-cloud.md](../infrastructure/cloud-providers/multi-cloud.md). + +## Cost gotchas + +Non-obvious patterns that read as cheap but bill like they are not — classify these conservatively (at least 🟠 orange): + +- **NAT Gateway data-processing charges** — the hourly rate is small; the per-GB processing on every byte to the internet is the real bill. +- **S3/CloudFront egress**, not storage — storage is pennies; data transfer out is where the money goes. +- **CloudWatch Logs / high-cardinality metrics** — verbose logging or per-request custom metrics can outgrow the compute they observe. +- **DynamoDB GSIs** — each global secondary index is a full second copy of write throughput and storage. +- **Kinesis / provisioned shards** — a floor cost per shard whether or not data flows. +- **Cross-AZ / cross-region traffic** — inter-AZ data transfer is billed and easy to introduce accidentally. +- **LLM context bloat** — per-token pricing makes large prompts/long context windows scale cost linearly with every call; retries and agent loops multiply it. +- **"Serverless" that never sleeps** — a scheduled job or warmer keeping a function hot removes the scale-to-zero benefit. +- **Free-tier cliffs** — a signal that is free at low volume can jump a class once past the free tier; classify by expected steady-state volume, not the demo. + +## Relationship to the quality model + +- The **class scale** and the **resolution cascade** (Argument > Adoption > KB default) are owned by [quality-model.md](quality-model.md) §3.3 — not restated here. +- This guideline owns the **catalog** and the **heuristics**; `assess-cost` is the skill that applies them (three-layer principle, §1 of the quality model). +- Cost is its **own class**, never folded into the risk `max` (§3.2); it is projected as the `cost:*` tag only if a project opts in via `tech/risk-matrix.md`'s Tag Projection (§5). diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md index 0d17924a..f01c49f6 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md @@ -18,7 +18,7 @@ The single source of default quality rules for this KB. `classify`, `assess-cost | Pillar | Covers | Tag family (if exposed) | Primary skill | | --- | --- | --- | --- | -| **Cost** | Financial exposure of building/running the change | `cost:*` — opt-in, §5 | `assess-cost` (cost-signal catalog, forthcoming) | +| **Cost** | Financial exposure of building/running the change | `cost:*` — opt-in, §5 | `assess-cost` (cost-signal catalog) | | **Security** | Vulnerabilities, compliance, secure-by-design | none dedicated — feeds `risk:*` (§3) + deterministic CI scanning | `assess-security`, [security/](security/README.md) | | **Delivery** | Everything else: correctness, performance, a11y, observability, docs, planning, architecture, release, AI metrics | `risk:*` (correctness/blast-radius facets) — KB default, §5 | `pair-process-review`, `classify` | @@ -52,7 +52,7 @@ Coupling sources absent (no subdomain/bounded-context artifacts, no `assess-coup ### 3.3 Cost class (R6.2) -Cost class = **highest detected signal**. The signal catalog (paid-SDK imports, API-key env vars, IaC/provisioning changes, cron/queues, media processing, LLM calls) is maintained in the cost-assessment guideline (forthcoming, `assess-cost`); no signal detected ⇒ `green`. General + provider-specific heuristics: [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). This value is always computed and written to the story/PR body's matrix (§1); it is projected as the `cost:green|yellow|orange|red` tag only if a project adds `cost` to its Tag Projection declaration (§5) — the KB does not do this by default. +Cost class = **highest detected signal**. The signal catalog (paid-SDK imports, API-key env vars, IaC/provisioning changes, cron/queues, media processing, LLM calls) is maintained in the [cost-assessment guideline](cost-assessment.md), applied by `assess-cost`; no signal detected ⇒ `green`. General + provider-specific heuristics (AWS first, other providers via adoption links) live there too; deeper running-cost optimization is in [infrastructure/cloud-providers/cost-optimization.md](../infrastructure/cloud-providers/cost-optimization.md). This value is always computed and written to the story/PR body's matrix (§1); it is projected as the `cost:green|yellow|orange|red` tag only if a project adds `cost` to its Tag Projection declaration (§5) — the KB does not do this by default. ## 4. Per-Tier Requirements @@ -166,4 +166,4 @@ Every quality theme not covered by §1–§6 lives under one of the three pillar | Release | Delivery | [../technical-standards/deployment-workflow/release-management.md](../technical-standards/deployment-workflow/release-management.md) | | AI metrics / retro | Delivery | [../collaboration/project-tracking/README.md](../collaboration/project-tracking/README.md) (reports land in `.pair/working/reports/`, once available) | | Vulnerabilities / compliance | Security | [security/vulnerability-prevention.md](security/vulnerability-prevention.md), [security/compliance.md](security/compliance.md) | -| Cost signals | Cost | cost-assessment guideline (not yet published, see §3.3) | +| Cost signals | Cost | [cost-assessment.md](cost-assessment.md) (see §3.3) | diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index fb6b9e82..7974b47a 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/next` at the start of every session. It reads project adoption files and P | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 28 | Atomic units — perform a single focused operation | +| **Capability** | 29 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 38 (9 process + 28 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 39 (9 process + 29 capability + 1 navigator). ## Full Catalog @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) were removed — domain modeling is referenced inline by each real caller's own how-to (02, 03, 06, 09; 08 planned — #242). See [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (28) +### Capability Skills (29) #### Domain Modeling Skills (2) @@ -48,7 +48,7 @@ Process skills compose capability skills. Capability skills are independently in Reclassified from process to capability (D24) — see [Callers Matrix](#callers-matrix-scoped-capabilities) and [Migration Notes](#migration-notes). -#### Assessment Skills (9) +#### Assessment Skills (10) | Skill | Scope | |-------|-------| @@ -61,6 +61,7 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/assess-observability` | Observability strategy evaluation | | `/assess-ai` | AI development tools evaluation | | `/assess-security` | Security posture — review verdict (`$mode: review`, composed by `/review`) + one-shot OWASP Top 10 audit (`$mode: audit`). Unlike the 8 above, not purely output-only — writes its own audit report (D14 exception); never scans for secrets, that's the deterministic CI layer `/setup-gates` provisions (D24) | +| `/assess-cost` | Cost exposure — chromatic class (`cost:green\|yellow\|orange\|red`) from the diff/story against the [cost-signal catalog](guidelines/quality-assurance/cost-assessment.md) (general + AWS-first, other providers via adoption links). Output-only: feeds `/classify`'s cost dimension, writes nothing, blocks nothing; report/monitoring mode is a separate slice | #### Classification Skills (1) diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md b/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md index 26212732..4a23e1c4 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md @@ -78,4 +78,4 @@ The process is designed to: 2. **🤖🤝👨‍💻 Code Review** (`/review`) → Structured review with adoption compliance, merge flow, and parent cascade 3. **🤖⚡ Status Update** → Automatic story/epic/initiative tracking update (handled by `/implement` and `/review`) -> **Skill-enabled workflow**: Run `/next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 38 skills. +> **Skill-enabled workflow**: Run `/next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 39 skills. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md new file mode 100644 index 00000000..9048235f --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md @@ -0,0 +1,132 @@ +--- +name: assess-cost +description: "Classifies the financial exposure of a change as a chromatic cost class (green/yellow/orange/red) at review or on demand, by scanning the diff/story for cost signals against the KB cost-signal catalog resolved through the project's stack/architecture/infrastructure adoption. Output-only: emits the cost dimension of the classification matrix (1-line verdict + collapsed details, D22) for /classify and /review to consume — writes nothing, blocks nothing. Multi-provider by construction: adding a provider touches adoption/KB only, never this skill." +version: 0.1.0 +author: Foomakers +--- + +# /assess-cost — Cost Assessment + +Classify the financial exposure of a change as a chromatic **cost class** (`green` / `yellow` / `orange` / `red`) from the cost signals present in the diff (or, at refinement, the story scope), against a rule set resolved from the [quality model](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) (§2 Cost pillar, §3.3 Cost class) plus the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) — the single home of the cost-signal catalog, the general + provider-specific heuristics (AWS first), and the cost gotchas. + +**Output-only.** This skill emits the cost dimension of the classification matrix and nothing else: it **writes no files, creates no backlog items, and never blocks** a PR or merge (it has no such authority — the merge decision stays with `/review`, exactly as the `assess-security` sibling reports a verdict but never blocks). The cost class it computes is consumed by `/classify` and `/review`; the skill never interprets or acts on its own verdict. + +**Provider-agnostic core (R2.13).** No provider names are hardcoded in this skill. Which heuristics apply is selected by the project's `tech-stack.md` / `architecture.md` / `infrastructure.md` adoption files (Q3); the catalog and per-provider heuristics live in the guideline (D17/D21). Adding a provider is an adoption/KB change (a new per-provider section or an adoption link), never a change to this skill. + +## Arguments + +| Argument | Required | Description | +| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `$diff` | No | The PR/branch diff to classify. Default when invoked by `/review` or against a branch: the current diff. | +| `$story` | No | A story/issue to classify from its declared scope instead of a diff — the refinement-time (shift-left) path, mirroring the risk matrix built twice. | +| `$scope` | No | Area/package to scope the scan (default: the whole diff/story). Package-scoped only — never narrows the rule set, only the surface scanned. | + +`$diff` and `$story` are mutually exclusive inputs; exactly one surface is classified per run. Neither provided → auto-detect: a PR/diff in context (i.e. invoked by `/review`) → `$diff`; a story in context (i.e. invoked by `/refine-story`/`/classify` in refinement) → `$story`. + +## Rule Set + +Every rule resolves through the standard **Argument > Adoption > KB default** cascade of the quality model (§quality-model.md resolution order): + +1. **KB default** — [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) §3.3 (class = highest detected signal; class token `cost:green|yellow|orange|red`) + the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) (the signal catalog, the general heuristics, the per-provider heuristics starting with AWS, the gotchas). +2. **Provider selection (adoption)** — read `tech-stack.md`, `architecture.md`, `infrastructure.md`: the declared cloud/provider (e.g. AWS) selects which per-provider heuristics in the guideline apply. A provider the guideline does not cover in-tree is reached via an **adoption link** the adoption file supplies (fallback/extension — no skill change, Q3). +3. **Project delta (adoption)** — `tech/risk-matrix.md` `## Overrides` may tune cost thresholds (e.g. reclassify a shared path); absent ⇒ KB defaults apply completely (D21). + +A missing/malformed adoption file is treated as absent: warn and fall back to KB defaults (D21) — never HALT on adoption absence. + +## Algorithm + +### Step 0: Load the Quality Model (BLOCKING prerequisite) + +1. **Check**: Does [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) resolve (KB installed)? +2. **Act**: If it is **missing**, **HALT** — the quality model is a prerequisite, not a default this skill can invent. Report: _"Quality model not found — install/bootstrap the KB (`quality-model.md` §3.3) before running assess-cost."_ +3. **Verify**: The Cost class section (§3.3) and the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md) are loaded. + +### Step 1: Resolve the Rule Set + +1. **Act**: Read the KB default (§3.3 + cost-assessment guideline), then the adoption files (Rule Set layers 2–3), skipping any that don't exist. +2. **Act**: Select the applicable per-provider heuristics from the declared stack/infrastructure (e.g. AWS); for a provider only reachable via an adoption link, resolve that link. +3. **Verify**: Effective catalog + heuristics assembled. Adoption absence is logged as "KB defaults only", not an error. + +### Step 2: Resolve the Surface + +1. **Act**: Determine the surface: `$diff` (touched files/hunks) or `$story` (declared scope — infra/service load the story introduces), narrowed by `$scope` if given. +2. **Verify**: A concrete surface (file set or story scope) is resolved. + +### Step 3: Scan for Cost Signals + +1. **Act**: Scan the surface against the cost-signal catalog (maintained in the [cost-assessment guideline](../../../.pair/knowledge/guidelines/quality-assurance/cost-assessment.md)) — e.g. paid-SDK imports (payment/LLM/messaging providers), API-key env vars, IaC/provisioning changes, cron/scheduled jobs, queues/pipelines, media processing, LLM calls. For each hit, record the signal, its location, and the class it maps to per the guideline's heuristics (general + the selected provider's). +2. **Act**: **Unresolvable cost surface** (unknown tech whose cost profile the catalog + adoption cannot resolve): record it as an **unknown-surface** hit and assign it **orange** — the conservative, visible middle-high, never silently green (edge case: "unknown surface" flag). +3. **Verify**: Every touched cost-relevant surface has a signal, a location, and a mapped class; unknown surfaces are flagged, not dropped. + +### Step 4: Compute the Class + +1. **Act**: **Cost class = the highest detected signal** across all hits (§3.3). **No signal detected ⇒ `green`** with rationale _"no cost surface touched"_ (AC4). +2. **Act**: In refinement (`$story`) the class is the shift-left, declared value; in review (`$diff`) it is the observed value — carried in the same compiled matrix as its own class (never folded into the risk `max`, §3.2), tag token `cost:green|yellow|orange|red`. +3. **Verify**: Exactly one class computed, with a 1-line rationale and the detected-signals list. + +### Step 5: Emit the Verdict + +1. **Act**: Render the 1-line class + rationale and the collapsed `
` signals table per Output Format below — **output-only, no files written**. This is embedded by the caller into the classification matrix's cost dimension (D22 — verdict in ~1 line, details in `
`), consumed by `/classify` and shown by `/review`. +2. **Verify**: Verdict emitted. A `red` (or flagged unknown-surface) class is reported for the caller's attention; the skill itself blocks nothing — the merge decision stays `/review`'s. + +## Output Format + +```text +COST ASSESSMENT (output-only — no files written): +├── Class: [green | yellow | orange | red] — [1-line rationale] +├── Surface: [diff | story #ID | scope ] +├── Signals: [N detected — N unknown-surface] +├── Rule Set: [KB default | + provider | + adoption tech/risk-matrix.md] +└── Feeds: Cost dimension of the classification matrix (quality-model §3.3) — own class, not part of the risk max + +
+N cost signals + +| Signal | Location | Class | Notes | +| ------ | -------- | ----- | ----- | +| [signal] | [file:location] | [green|yellow|orange|red] | [provider heuristic / unknown-surface] | +... + +
+``` + +No signal detected renders as: `Class: green — no cost surface touched` with an empty (or omitted) signals table. + +## Composition Interface + +When composed by `/review` (review-time cost dimension): + +- **Input**: the reviewing skill invokes `/assess-cost` against the PR diff (`$diff`). +- **Output**: returns the class + collapsed signals (Output Format above). The caller embeds it into the review report's cost section (1 line + `
`, D22) and feeds the class into `/classify`'s cost dimension. +- **Persistence**: none — this skill writes nothing. + +When composed by `/refine-story` / `/classify` (shift-left, refinement): + +- Classifies from `$story` scope, producing the declared cost class carried in the story-body matrix — the review pass may only confirm-or-raise it, never lower it (D17 "built twice": the class is estimated from story context at refinement and re-derived from the diff at review — the more conservative of the two wins). + +When invoked **independently** (`/assess-cost` on a branch or story): full one-shot classification, verdict returned to the developer. + +> Review-side wiring (listing `/assess-cost` as a Composed Skill in `/review` and adding the cost section to the review template) is delivered separately (#228). This skill is authored ready-to-compose; nothing here depends on that wiring existing yet. + +## Edge Cases + +- **No cost-relevant change** (AC4): class `green`, rationale "no cost surface touched". +- **Unresolvable cost surface** (unknown tech): class `orange` with an explicit **unknown-surface** flag — conservative and visible, never silently green (Step 3.2). +- **Quality model missing**: **HALT** with a pointer to install/bootstrap the KB (Step 0) — the model is a prerequisite, not something this skill invents. +- **Provider not covered in-tree**: resolved via the adoption link the adoption file supplies (fallback/extension) — no skill change (Q3). +- **Adoption file missing/malformed**: warn, fall back to KB defaults (D21) — never a HALT. + +## Graceful Degradation + +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: + +- **cost-assessment guideline absent** (KB partially installed): assess against quality-model §3.3's inline signal list only, and note the reduced catalog in the output rather than HALTing. +- **`/classify` not available** (independent invocation): the class is still emitted; it simply isn't folded into a compiled matrix by a caller — the developer reads the verdict directly. + +## Notes + +- **Writes nothing** — the strict output-only convention of the assess-* family (unlike `assess-security`, this skill has no report/audit mode: report/monitoring is deliberately split to a separate slice). The class is data for `/classify`/`/review`, never an action this skill takes. +- **Never blocks** — no merge authority; a `red` class is a signal for the caller, not a gate this skill enforces. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. +- **Provider-agnostic** — adding a provider is an adoption/KB change (a per-provider section in the guideline, or an adoption link), never a change to this skill (R2.13). +- **D22** (1-line verdict + collapsed details): a project-level rendering decision the caller honors; this skill emits in that shape. diff --git a/packages/knowledge-hub/dataset/.skills/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index 55ece22b..80861833 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /next — Project Navigator -Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 38-skill catalog across all lifecycle phases. +Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 39-skill catalog across all lifecycle phases. ## Arguments (optional) @@ -37,9 +37,9 @@ Keep only candidate issues that carry the given label. `--filter` takes a **sing The scope is **stateless across steps**. Every run — and every step of a multi-step run — re-queries the PM tool and **re-evaluates** `--root` and `--filter` against the **current** board state. If an issue's tags change between steps (e.g. a review raises `risk:yellow` → `risk:red`), the next step's selection reflects the change immediately. `/next` never reuses a selection computed in a previous step. -## Skill Catalog (38 skills) +## Skill Catalog (39 skills) -The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 28 capability + `/next` itself = 38. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. +The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 29 capability + `/next` itself = 39. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. ### Process Skills (9) @@ -55,7 +55,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde | `/implement` | Sprint Execution | Implement story tasks with TDD | | `/review` | Sprint Execution | Review PR through structured phases | -### Capability Skills (28) +### Capability Skills (29) | Skill | Category | Description | | ------------------------ | --------------- | ---------------------------------------------------------------------------- | @@ -80,6 +80,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde | `/assess-infrastructure` | Assessment | Assess infrastructure strategy | | `/assess-observability` | Assessment | Assess observability strategy | | `/assess-security` | Assessment | Assess security posture (review verdict + one-shot audit) | +| `/assess-cost` | Assessment | Classify cost exposure (green/yellow/orange/red) at review — output-only | | `/analyze-debt` | Analysis | Analyze technical debt with prioritization | | `/analyze-code-quality` | Analysis | Analyze code quality with metrics | | `/estimate` | Planning | Estimate story using adopted methodology | @@ -217,4 +218,4 @@ See [graceful degradation](../../.pair/knowledge/skill-conventions/graceful-degr - This skill is read-only: it inspects state but never modifies files or PM tool data. - Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: nearly all of the 38 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/checkpoint`, rows 12-16 including `/grill`) or process-skill composition. `/publish-pr` will be reachable via `/implement` once wired (not yet composed), so `/next` cannot surface it today. +- **Full catalog coverage**: nearly all of the 39 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/checkpoint`, rows 12-16 including `/grill`) or process-skill composition. `/publish-pr` will be reachable via `/implement` once wired (not yet composed), so `/next` cannot surface it today. diff --git a/packages/knowledge-hub/src/conformance/assess-cost.test.ts b/packages/knowledge-hub/src/conformance/assess-cost.test.ts new file mode 100644 index 00000000..76c31cfd --- /dev/null +++ b/packages/knowledge-hub/src/conformance/assess-cost.test.ts @@ -0,0 +1,129 @@ +import { describe, it, expect } from 'vitest' +import { readFileSync, existsSync } from 'fs' +import { join } from 'path' + +// Conformance guard for story #226: pair-capability-assess-cost is an OUTPUT-ONLY, +// multi-provider cost classification shown at review (green/yellow/orange/red per +// quality-model §3.3). Consistent with the assess-security sibling: it emits a +// verdict, writes nothing, blocks nothing. The cost-signal catalog + general/AWS +// heuristics + gotchas live in the KB guideline (cost-assessment.md), never in the +// skill (D17/D21). Review-side wiring (compose into /review) and the review template +// land separately (#228) and are deliberately NOT asserted here. + +const DATASET_SKILLS = join(__dirname, '../../dataset/.skills') +const MIRROR_SKILLS = join(__dirname, '../../../../.claude/skills') +const DATASET_KB = join(__dirname, '../../dataset/.pair/knowledge') +const MIRROR_KB = join(__dirname, '../../../../.pair/knowledge') + +const ASSESS_COST_DATASET = readFileSync( + join(DATASET_SKILLS, 'capability/assess-cost/SKILL.md'), + 'utf-8', +) +const ASSESS_COST_MIRROR = readFileSync( + join(MIRROR_SKILLS, 'pair-capability-assess-cost/SKILL.md'), + 'utf-8', +) +const COST_GUIDELINE_DATASET = readFileSync( + join(DATASET_KB, 'guidelines/quality-assurance/cost-assessment.md'), + 'utf-8', +) +const COST_GUIDELINE_MIRROR = readFileSync( + join(MIRROR_KB, 'guidelines/quality-assurance/cost-assessment.md'), + 'utf-8', +) +const NEXT_DATASET = readFileSync(join(DATASET_SKILLS, 'next/SKILL.md'), 'utf-8') +const NEXT_MIRROR = readFileSync(join(MIRROR_SKILLS, 'pair-next/SKILL.md'), 'utf-8') +const SKILLS_GUIDE_DATASET = readFileSync(join(DATASET_KB, 'skills-guide.md'), 'utf-8') +const SKILLS_GUIDE_MIRROR = readFileSync(join(MIRROR_KB, 'skills-guide.md'), 'utf-8') + +describe('assess-cost.md — skill structure (#226)', () => { + for (const [label, content] of [ + ['dataset', ASSESS_COST_DATASET], + ['mirror', ASSESS_COST_MIRROR], + ] as const) { + it(`${label} is declared output-only (writes nothing, blocks nothing)`, () => { + expect(content.toLowerCase()).toContain('output-only') + // No adoption-write step — the skill never persists anything itself. + expect(content).not.toMatch(/#+\s*Step\s*\d+:\s*Write Adoption File/i) + expect(content.toLowerCase()).toMatch(/never blocks|does not block|no blocking/) + }) + + it(`${label} emits the §3.3 cost class token green|yellow|orange|red`, () => { + expect(content).toContain('cost:green|yellow|orange|red') + }) + + it(`${label} feeds the classification matrix cost dimension with a 1-line verdict + details (D22)`, () => { + expect(content).toContain('D22') + expect(content.toLowerCase()).toContain('
') + }) + + it(`${label} keeps the signal catalog in the guideline, not the skill (D17/D21)`, () => { + expect(content).toContain('cost-assessment.md') + expect(content).toMatch(/D17|D21/) + }) + + it(`${label} is provider-agnostic — no hardcoded provider list, providers via adoption/KB`, () => { + expect(content.toLowerCase()).toMatch(/provider-agnostic|no provider names/) + }) + + it(`${label} HALTs when the quality model is missing`, () => { + expect(content).toMatch(/HALT/) + expect(content.toLowerCase()).toContain('quality model') + }) + + it(`${label} defaults to green when no cost surface is touched (AC4)`, () => { + expect(content.toLowerCase()).toContain('no cost surface') + }) + } +}) + +describe('cost-assessment.md — guideline (#226 T2)', () => { + for (const [label, content] of [ + ['dataset', COST_GUIDELINE_DATASET], + ['mirror', COST_GUIDELINE_MIRROR], + ] as const) { + it(`${label} defines the multi-provider cost-signal catalog`, () => { + expect(content.toLowerCase()).toContain('cost-signal catalog') + // A representative sample of the catalog signals must be present. + for (const signal of ['paid-SDK', 'IaC', 'cron', 'queue', 'LLM']) { + expect(content).toContain(signal) + } + }) + + it(`${label} maps signals to the green|yellow|orange|red class scale`, () => { + expect(content).toContain('cost:green|yellow|orange|red') + expect(content.toLowerCase()).toContain('highest detected signal') + }) + + it(`${label} has an AWS-specific section and points other providers to adoption links`, () => { + expect(content).toMatch(/## .*AWS/) + expect(content.toLowerCase()).toMatch(/adoption link|adoption-link/) + }) + + it(`${label} has a cost gotchas section`, () => { + expect(content.toLowerCase()).toContain('gotcha') + }) + } +}) + +describe('assess-cost catalog registration (#226)', () => { + it('dataset skill directory exists', () => { + expect(existsSync(join(DATASET_SKILLS, 'capability/assess-cost/SKILL.md'))).toBe(true) + }) + + for (const [label, next, guide] of [ + ['dataset', NEXT_DATASET, SKILLS_GUIDE_DATASET], + ['mirror', NEXT_MIRROR, SKILLS_GUIDE_MIRROR], + ] as const) { + it(`${label} next catalog lists assess-cost and states 29 capability / 39 total`, () => { + expect(next).toMatch(/assess-cost/) + expect(next).toContain('29 capability') + expect(next).toContain('39 skills') + }) + + it(`${label} skills-guide lists assess-cost and states 29 capability / 39 total`, () => { + expect(guide).toMatch(/assess-cost/) + expect(guide).toContain('29 capability') + }) + } +})