assess-cost report mode — deploy/billing telemetry integration for deploy-match

[rucka]

Story Statement

As a team monitoring cost drift with /pair-capability-assess-cost $mode: report
I want the panel's deploy-match dimension to resolve a merge to its deployment and to the observed cost movement, with the provider APIs described in the KB rather than inside the skill
So that predicted-vs-real cost monitoring can be corroborated by billing reality — and a second provider costs an adoption link, not a skill change

Where: a new telemetry guideline under guidelines/quality-assurance/quality-monitoring/, the ## Cost & Billing Telemetry declaration in infrastructure.md, and assess-cost Step 9.2 (dropping its "deferred" note).

Epic Context

Parent Epic: Unified classification & assessments → tags #208
Status: Refined
Priority: P2 (Could-Have) — confirmed during refinement, and the reason is now explicit: see "What this story is not" below

Classification

risk:yellow · cost: green (not projected — Active: risk only)

Matrix — per dimension

Dimension	Tier	Source	Note
Service/domain criticality	green	Criticality Table	tech/risk-matrix.md now lists every deployable explicitly; touched scope resolves to packages/knowledge-hub → Low
Change/diff risk	yellow	story scope	New guideline + adoption schema + one skill step — 3 distinct content areas; change-risk.dataset-mirror-pairs collapses the skill's dataset source + its .claude/skills mirror into one, but doesn't merge that with the separate guideline/adoption-schema changes. Additive: the degraded path stays the default, so no existing behaviour changes
Business impact	yellow	subdomain class	Integration & Process Standardization (Supporting) — the new Development Tooling Standards Generic subdomain covers lint/format/TS-config/brand tooling only, unrelated to this story's scope, so it doesn't apply here
Security relevance	yellow	path heuristic	Security-adjacent: introduces two external integrations that need credentials (a code-host token for deployments, a read-only billing role). No secret may live in adoption; minimum permissions are part of the guideline
Coupling balance	green	subdomain volatility + integrations	The skill couples to a declaration, not to a provider — every provider is reached through adoption (R2.13), which is what keeps this balanced

Tier = yellow (max rule). tier-resolution.default-artifact-downgrade does not apply here: it only forgives a would-be-yellow whose yellows are confined to Service/domain-criticality and/or Business-impact, but this diff also carries yellow on Change/diff-risk and Security-relevance, which stay pure weakest-link. Gate checks for 🟡: lint + type + build + unit.

Re-classified 2026-08-14 against corrected adoption inputs (Criticality Table now lists every deployable; Development Tooling Standards Generic subdomain now exists but doesn't cover this story's scope) — Service/domain criticality moved yellow→green; overall tier unchanged at yellow because Change/diff-risk and Security-relevance remain yellow.

Problem

assess-cost report mode (#281, PR #388) declares a deploy-match dimension: with deploy/billing telemetry declared, it should match a merged PR to its deployment and record the observed cost movement. As shipped, only the degraded branch is executable — every project reports not available, because:

• no in-tree integration resolves a merge commit → deployment;
• no in-tree integration queries a per-service billing metric;
• no project declares the ## Cost & Billing Telemetry section the skill looks for.

#281's spec names the declaration and the definition of "observed cost movement" as a contract and marks the matched path deferred, pointing here. Review finding on PR #388 (Minor): the positive path otherwise reads as a promise the spec cannot deliver.

What this story is not (scope, settled during refinement)

assess-cost's core job is classifying a change's cost exposure from the code: the signal catalog (paid-SDK imports, API-key env vars, IaC changes, cron/queues, media processing, LLM calls) applied to the diff or the story's declared scope. That is unchanged and untouched here.

Cost monitoring is also in the mandate — quality-model §3.3 states "Cost monitoring (R6.3/R6.4) → assess-cost report mode" — but what R6.3/R6.4 require is diff-based: compare the class predicted at refinement with the real class of the merged diff, and surface systematic drift periodically. Both measurements come from the code and the catalogue. No bill is involved, and that half already works (#281).

This story is the extra: corroborating the prediction against actual spend. That is why it is P2 and why the degraded path must remain permanently correct — a project without billing telemetry is not missing a feature, it is on the supported default.

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a complete ## Cost & Billing Telemetry declaration in infrastructure.md
   When the period panel is rendered
   Then a merged PR's row carries the matched deployment and the observed cost movement

2. Given the declaration is absent or incomplete
   When the panel is rendered
   Then the row reads not available — never a fabricated or inferred match

3. Given the new guideline
   When it is authored
   Then it describes the provider APIs explicitly: for the code host, the deployments endpoint, the fields consumed (commit sha, environment, creation timestamp) and their semantics; for billing, the metric queried, its granularity and the query window. The skill names no provider (R2.13) — it resolves what the adoption declares

4. Given a project on a second billing provider or a different deploy source
   When it is added
   Then only KB/adoption change — never the skill

5. Given a matched deployment
   When the cost movement is computed
   Then it is the delta in the declared billing metric for the deployed service between equal-length windows before and after the deployment, with that definition living in the guideline

6. Given the integrations need credentials
   When the guideline documents them
   Then it states the minimum read-only permissions required and forbids any credential in adoption files — the declaration names where to look, never a secret

7. Given a billing metric that is not yet consolidated for the post-deploy window (providers can lag by a day or more)
   When the panel runs
   Then the row reads not available — billing window not yet consolidated, distinct from a missing declaration, and never a partial delta presented as final

8. Given a merge with no corresponding deployment (never deployed, or deployments not recorded)
   When the match is attempted
   Then not available with that reason, distinct from an absent declaration

9. Given several deployments for the same commit (redeploys, multiple environments)
   When the match is resolved
   Then the rule is the one stated in the guideline — the first deployment that shipped that merge into the declared environment — applied deterministically

10. Given report mode
    When anything above fails
    Then it still never blocks a merge or a release (report mode is advisory by construction)

11. Given the conformance guard
    When it runs
    Then it asserts both branches on the skill spec — matched and degraded — so the positive path cannot silently become a promise again

Business Rules

• Provider APIs live in the KB guideline, never in the skill (R2.13, D17/D21). The skill applies rules it does not hold.
• The guideline's home is quality-monitoring/, not cost-assessment.md — that document declares itself "about classifying a change at review, not tuning a bill", so putting billing telemetry there would contradict its own scope statement.
• The degraded path is permanent, not transitional. not available is the correct output for a project without telemetry, forever.
• No inferred matches. A plausible number is worse than an honest absence in a report about money.
• No credentials in adoption. The declaration is a pointer; permissions are documented as minimum and read-only.
• Report mode never blocks (unchanged).

Edge Cases and Error Handling

• Billing consolidation lag: covered by AC7 — the window may not be final when the panel runs; a partial delta must not be rendered as the movement.
• Shared service: if the declared metric covers a service used by more than the deployed change, the movement is not attributable — not available with that reason rather than a number nobody can defend.
• Monorepo merge touching several services: the declaration maps metric per service; a merge spanning services yields one row per attributable service, or not available where attribution is impossible.
• Provider price change inside the window: a confounder, not a prediction error — the same treatment §3.3 already gives to a catalogue change inside a monitored window, and stated as such in the panel.
• Redeploy of the same commit: AC9's deterministic rule.
• Deploy source reachable, billing unreachable (or vice versa): report which half resolved; a half-resolved match is not available, not a partial claim.

Definition of Done Checklist

• All acceptance criteria implemented and verified
• Test written first and failing before the change
• New guideline under guidelines/quality-assurance/quality-monitoring/ describing: deploy-source API (endpoint, fields, semantics), billing-metric API (metric, granularity, window), the equal-length window definition, the multi-deployment rule, consolidation lag, and minimum read-only permissions
• ## Cost & Billing Telemetry declaration shape + example documented; assess-infrastructure / bootstrap aware of it
• assess-cost Step 9.2 updated — "deferred" note dropped, no provider named in the skill
• Conformance guard asserting both branches (matched + degraded) on the skill spec
• Registered in the guidelines catalog + docs site
• Dataset edited as source, mirror regenerated (pair update), skills:conformance green
• 🟡 gate checks green: lint + type + build + unit

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Low-Medium — the only card in the active set whose behaviour cannot be fully verified in-tree
Sizing Justification: The guideline is the bulk: two provider APIs described precisely enough to be implemented from, plus window semantics, attribution rules and permission requirements. The skill change is small. Confidence is low because the real integrations need a project with actual deployments and a billing account — so the matched path is validated by fixtures in-tree and by one manual run out of tree, not by CI.

Sprint Capacity Validation

Sprint Fit Assessment: Yes
Development Time Estimate: ~1 day
Testing Time Estimate: ~0.5 day in-tree (fixtures) + a manual verification wherever telemetry actually exists

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #281 merged ✅ (report mode + the contract this fills)
Dependent Stories: none
Shared Components: pair-capability-assess-cost (no other active card touches it), the guidelines catalog

External Dependencies

Third-party: a deploy source exposing "this commit reached this environment, at this time" (GitHub Deployments for this code host) and a billing metric API (AWS Cost Explorer first, per the KB's provider order). Both reached through adoption, so neither is a build-time dependency of the skill.
Related decisions: R6.3/R6.4 (cost monitoring) · R2.13 (multi-provider through adoption) · quality-model §3.3 · cost-assessment.md (scope boundary: classification, not billing) · the report-panel convention (working-area.md, ADL 2026-07-28)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: conformance guard over the skill spec (both branches); fixture-driven tests for the panel row — complete declaration, absent declaration, incomplete declaration, no deployment found, unconsolidated window, multiple deployments; and one manual end-to-end verification on a project that really declares telemetry, recorded in the panel output. No test may call a live billing API in CI.
Test Data Requirements: fixture infrastructure.md declarations (complete / partial / absent), fixture deployment payloads, fixture billing series including an unconsolidated tail.

Success Metrics

• A project with telemetry declared gets a matched deployment and a defensible cost movement
• A project without it reads not available — and that stays true and correct indefinitely
• Adding a provider touches adoption/KB only, verified by the conformance guard

Notes and Additional Context

Refinement Session Insights (2026-08-05):

1. Scope clarified before anything else. The question raised was whether assess-cost should only analyse costs from code and implementation. Verified: the classification core is exactly that, and the monitoring the requirements ask for (R6.3/R6.4) is also diff-based — predicted class vs. real class of the merged diff, no bill involved. That half already ships. This card is the extra corroboration against real spend, which is why it is P2 and why the degraded path is permanent rather than a placeholder.
2. The APIs belong in the guideline — the constraint that shaped this refinement. The skill holds no provider knowledge (R2.13); the guideline describes endpoints, fields and windows precisely enough to implement from.
3. The guideline's home is not cost-assessment.md. That file states its own scope as "classifying a change at review, not tuning a bill"; billing telemetry goes to quality-monitoring/, which owns observability and reporting.
4. Consolidation lag is the trap (AC7). Billing data arrives late; a panel that computed a delta over an unconsolidated window would report a confident number that changes tomorrow — in a cost report, that is worse than reporting nothing.

Team Concerns: this is the first card introducing an external integration that needs credentials. The permission surface (read-only deployments, read-only billing) must stay minimal and documented, and the declaration must never carry a secret — the repo's secret-scanning layer is a backstop, not the design.

Technical Analysis

Implementation Approach

Technical Strategy: describe the two provider APIs and the comparison semantics in a new KB guideline; have the skill read a declaration that points at them; keep the degraded branch as the default and make both branches assertable.

Key Components:

• new guideline in guidelines/quality-assurance/quality-monitoring/ — deploy-source API, billing API, window semantics, attribution and multi-deployment rules, permissions
• infrastructure.md — ## Cost & Billing Telemetry declaration shape + example
• pair-capability-assess-cost Step 9.2 — matched path made real, "deferred" note removed, no provider named
• assess-infrastructure / bootstrap — awareness of the new declaration
• conformance guard + fixtures

Data Flow: merged PR → declaration → deploy source (commit → environment + timestamp) → billing metric over equal-length pre/post windows → movement → panel row (or not available with a specific reason).

Integration Points: code host (deployments), billing provider (metric), the period-keyed panel convention, assess-infrastructure.

Design: not required

Technical Risks and Mitigation

Risk	Impact	Mitigation
A provider name leaks into the skill	R2.13 broken: the next provider needs a skill change, and the skill starts holding rules	AC3/AC4 + conformance guard; the guideline is the only place naming an API
Cost movement computed over an unconsolidated window	A confident number that changes the next day, inside a report about money	AC7: explicit not available — billing window not yet consolidated
Attribution on a shared service	A cost movement blamed on a change that did not cause it	Edge case: not attributable ⇒ not available with reason
The guideline lands in cost-assessment.md	That document contradicts its own declared scope, and classification/monitoring blur together	Business rule fixes the home as quality-monitoring/
Credentials documented by example	A secret in an adoption file — exactly what the secret-scan layer exists to catch	AC6: minimum read-only permissions documented, credentials forbidden in adoption
The matched path cannot be tested in CI	It ships unverified and rots	Fixtures for every branch in-tree + one recorded manual verification; no live billing call in CI

Task Breakdown

• T-1: Write failing conformance assertions for the matched deploy-telemetry branch
• T-2: Author the Cost & Billing Telemetry guideline (deploy-source API, billing API, window/attribution/permission rules)
• T-3: Document the ## Cost & Billing Telemetry adoption declaration + wire assess-infrastructure/bootstrap awareness
• T-4: Implement assess-cost Step 9.2 matched path — drop "deferred", resolve via adoption, no provider named
• T-5: Fixture-driven tests for every panel-row branch (matched, absent/incomplete declaration, no deployment, unconsolidated window, multiple deployments, shared-service, half-resolved)
• T-6: Register the guideline in the guidelines catalog (README, llms.txt, docs site)
• T-7: Regenerate the KB mirror (pair update), run skills:conformance, and verify the 🟡 gate green

Dependency Graph

T-1 ── T-2 ──┬── T-3 ── T-4 ──┬── T-5 ── T-7
             └── T-6 ─────────┘

AC Coverage

AC	Tasks
AC-1 (complete declaration → matched deployment + movement)	T-2, T-3, T-4, T-5
AC-2 (absent/incomplete declaration → not available)	T-3, T-4, T-5
AC-3 (guideline names APIs explicitly; skill names none)	T-2, T-4
AC-4 (second provider → adoption/KB change only)	T-2, T-4
AC-5 (movement = equal-length pre/post window delta)	T-2, T-4
AC-6 (min read-only permissions; no credentials in adoption)	T-2, T-3
AC-7 (unconsolidated window → distinct not available)	T-2, T-4, T-5
AC-8 (no deployment found → distinct not available)	T-2, T-4, T-5
AC-9 (multiple deployments → deterministic first-shipped rule)	T-2, T-4, T-5
AC-10 (report mode never blocks)	T-4
AC-11 (conformance guard asserts both branches)	T-1, T-5

---

T-1: Write failing conformance assertions for the matched deploy-telemetry branch

Priority: P1 | Estimated Hours: 1.5h | Bounded Context: Integration & Process Standardization

Summary: Extend assess-cost.test.ts with assertions that the SKILL.md's matched deploy-telemetry branch is documented as executable, not deferred — written first so it fails against the current (pre-change) skill spec.

Type: Testing

Description: The existing guard (packages/knowledge-hub/src/conformance/assess-cost.test.ts:329-334) only asserts the word "deferred" appears — the exact statement this story removes. Per the repo's bug/feature test-first convention, write the target-state assertions now, confirm they fail, then let T-4/T-5 make them pass. New assertions: (a) Step 9.2 no longer contains "deferred" language describing the matched branch as unimplemented; (b) Step 9.2 references a KB guideline path (not an inline provider name) for the deploy-source and billing APIs; (c) no provider name (GitHub, AWS, Cost Explorer, etc.) appears inside pair-capability-assess-cost/SKILL.md itself (R2.13 guard).

Acceptance Criteria:

• Primary deliverable: new/updated it(...) blocks in assess-cost.test.ts covering (a)-(c) above.
• Quality standard: assertions run for both dataset and installed-mirror copies of the skill (existing label loop pattern at line 323).
• Integration requirement: reuses the existing test file's loop structure — no new test file.
• Verification method: pnpm vitest run -t "assess-cost" — all new assertions FAIL against the pre-change SKILL.md.

Technical Requirements:

• Functionality: assertions are string/regex based, matching the file's existing style (toMatch, toContain).
• Performance: n/a.
• Security: the "no provider name in skill" assertion is itself a security/coupling guard (R2.13) — must not admit an inline provider string.

Implementation Approach:

• Technical Design: add three new it(...) cases inside the existing label-parameterized describe block, near lines 323-334.
• Bounded Context & Modules: packages/knowledge-hub/src/conformance/.
• Files to Modify/Create:
  • packages/knowledge-hub/src/conformance/assess-cost.test.ts - add matched-branch + no-provider-name assertions.
• Technical Standards References:
  • AGENTS.md — Bug Resolution Workflow (test-first)
  • packages/knowledge-hub/src/conformance/assess-cost.test.ts (existing pattern, lines 1-20, 323-334)

Dependencies:

• Technical: none.
• Task Dependencies: none (first task).
• Resource Dependencies: none.

Implementation Steps:

1. Read the current guard's label/describe scaffolding (dataset + mirror paths).
2. Add the three assertions described above.
3. Run pnpm vitest run for this file — confirm all three FAIL against current SKILL.md.
4. Commit the failing test as the baseline for T-4/T-5.

Testing Strategy:

• Unit Tests: the conformance assertions themselves are the test artifact.
• Integration Tests: none at this step.
• Manual Testing: none.

Notes: This is KB/content work, not application code — "failing test" here means a failing conformance assertion against the shipped skill spec, the repo's equivalent of a red unit test for markdown/skill content.

---

T-2: Author the Cost & Billing Telemetry guideline

Priority: P0 | Estimated Hours: 4h | Bounded Context: Knowledge & Standards

Summary: New guideline under guidelines/quality-assurance/quality-monitoring/ describing the two provider APIs precisely enough to implement from, plus the semantics assess-cost Step 9.2 will point at.

Type: Documentation

Description: Per the story's business rule, this guideline's home is quality-monitoring/ — never cost-assessment.md, which explicitly scopes itself to "classifying a change at review, not tuning a bill". Content required (DoD + AC3/AC5/AC6/AC7/AC9): (1) deploy-source API — GitHub Deployments endpoint (the code host adopted per tech-stack.md), the fields consumed (commit SHA, environment, creation timestamp) and their semantics; (2) billing-metric API — AWS Cost Explorer (per the KB's AWS-first provider order, matching cost-assessment.md's AWS-specific heuristics section) — the metric queried, granularity, query window; (3) the equal-length pre/post window definition for "observed cost movement" (AC5); (4) the deterministic multi-deployment rule — first deployment that shipped the merge commit into the declared environment (AC9); (5) consolidation lag handling — billing data can lag a day or more, producing not available — billing window not yet consolidated, distinct from a missing declaration (AC7); (6) minimum read-only permissions for both integrations, and an explicit statement that no credential may live in adoption files (AC6); (7) the shared-service / non-attributable edge case (movement not attributable ⇒ not available with reason) and the provider price-change-inside-window confounder, per the story's edge cases.

Acceptance Criteria:

• Primary deliverable: cost-billing-telemetry.md (or equivalent name) under guidelines/quality-assurance/quality-monitoring/.
• Quality standard: every API described with enough precision (endpoint/fields/semantics for deploys; metric/granularity/window for billing) that Step 9.2 can be implemented from it without inventing behavior.
• Integration requirement: cross-links cost-assessment.md (scope boundary), quality-model.md §3.3, and the quality-monitoring/README.md index.
• Verification method: peer read-through against AC3/AC5/AC6/AC7/AC9 — each traceable to a section of the new file.

Technical Requirements:

• Functionality: describes both branches (matched + degraded) precisely — the degraded branch ("no declaration ⇒ not available, forever supported") is a first-class documented outcome, not an afterthought.
• Performance: n/a (documentation).
• Security: minimum read-only permission scopes are explicit and separable per integration (deploy read, billing read) — no combined/broad-scope credential recommended.

Implementation Approach:

• Technical Design: one new markdown file, structured like the sibling files in the directory (code-quality.md, performance-gates.md, observability-requirements.md) for house-style consistency.
• Bounded Context & Modules: guidelines/quality-assurance/quality-monitoring/.
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-monitoring/cost-billing-telemetry.md - new guideline (edited as source per the dataset-is-source convention).
• Technical Standards References:
  • .pair/knowledge/guidelines/quality-assurance/cost-assessment.md (scope boundary + AWS-first provider order)
  • .pair/knowledge/guidelines/infrastructure/cloud-providers/aws-deployment.md, cost-optimization.md (existing AWS API references)
  • .pair/knowledge/guidelines/quality-assurance/quality-model.md §3.3

Dependencies:

• Technical: none (documentation-only).
• Task Dependencies: T-1 (baseline failing test exists first).
• Resource Dependencies: none.

Implementation Steps:

1. Draft the deploy-source API section (GitHub Deployments: endpoint, commit SHA / environment / created_at fields, semantics of "first deployment that shipped this commit").
2. Draft the billing-metric API section (AWS Cost Explorer: metric, granularity, per-service query window).
3. Define the equal-length pre/post window computation and the multi-deployment determinism rule.
4. Document consolidation lag, shared-service non-attribution, and the price-change confounder as named edge cases.
5. Document minimum read-only permission sets for both integrations and the "no credentials in adoption" rule.
6. Cross-link cost-assessment.md, quality-model.md §3.3, and add the file to the directory's own internal consistency (naming, heading levels) with its siblings.

Testing Strategy:

• Unit Tests: none (documentation) — validated by T-1/T-5 conformance assertions referencing this file's existence/path.
• Integration Tests: n/a.
• Manual Testing: read-through against every AC this task covers.

Notes: This is "the bulk" per the story's own sizing justification — two provider APIs described precisely enough to be implemented from, plus window/attribution/permission rules.

---

T-3: Document the ## Cost & Billing Telemetry adoption declaration + wire assess-infrastructure/bootstrap awareness

Priority: P1 | Estimated Hours: 1.5h | Bounded Context: Knowledge & Standards

Summary: Add the declaration shape + a filled example to infrastructure.md's adoption schema documentation, and make assess-infrastructure (and the bootstrap checklist) aware that a project may declare this section.

Type: Documentation / Configuration

Description: infrastructure.md currently has no ## Cost & Billing Telemetry section anywhere in the KB or any project's adoption file (confirmed by search) — this is a genuinely new declaration shape. It must name (a) the deploy/release source that maps a merge to a deployment and (b) the billing/cost metric queried per service, pointing at T-2's guideline for the API/semantics detail, and must state explicitly that it is a pointer, never a credential (AC6). assess-infrastructure's Step 2 (Read Guidelines) / proposal-rendering step should recognize this section as an optional declaration it can propose when a project has both a deploy source and a billing account; the bootstrap checklist should reference it as an optional, not required, adoption item — the degraded (not available) path is the permanent default per the story's business rules.

Acceptance Criteria:

• Primary deliverable: the declaration shape (heading + required sub-fields) and one filled example added where infrastructure.md's schema/examples are documented.
• Quality standard: the example demonstrates a pointer-only declaration (no secret value, no inline token) — consistent with AC6.
• Integration requirement: assess-infrastructure SKILL.md references the new section as optional; bootstrap checklist references it without making it mandatory.
• Verification method: a fixture infrastructure.md with the section present validates against the shape T-4/T-5 expect.

Technical Requirements:

• Functionality: declaration is parseable deterministically (fixed heading text ## Cost & Billing Telemetry, fixed sub-fields for deploy source and billing metric).
• Performance: n/a.
• Security: declaration content is a pointer (which API, which environment/service) — never a secret; this constraint is stated inline in the schema doc, not only in T-2's guideline.
• Compatibility: absent/partial declaration must remain valid input (AC2) — schema doc states this is fully optional.

Implementation Approach:

• Technical Design: extend the adoption-file schema documentation (wherever infrastructure.md's declarable sections are catalogued) with the new section, following the same shape as other optional declarations in that file.
• Bounded Context & Modules: guidelines/adoption schema docs (Knowledge & Standards) with a touchpoint into the pair-capability-assess-infrastructure skill (Development Collaboration).
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-monitoring/cost-billing-telemetry.md - add the "Declaration shape" section with the fixed heading + example (declaration lives beside the guideline it's specified by).
  • .claude/skills/pair-capability-assess-infrastructure/SKILL.md - add awareness of the optional section in the relevant step.
  • How-to/bootstrap checklist file (.pair/knowledge/how-to/02-how-to-complete-bootstrap-checklist.md or dataset equivalent) - mention the section as optional.
• Technical Standards References:
  • .pair/adoption/tech/infrastructure.md (target adoption file shape)
  • .claude/skills/pair-capability-assess-infrastructure/SKILL.md Step 2/Step 4

Dependencies:

• Technical: T-2's guideline must exist first (declaration points at it).
• Task Dependencies: T-2.
• Resource Dependencies: none.

Implementation Steps:

1. Define the fixed declaration heading and required sub-fields (deploy source name/reference, billing metric name/reference, environment mapping).
2. Write one filled, pointer-only example (no secret values).
3. Update pair-capability-assess-infrastructure's SKILL.md to recognize/propose the section as optional.
4. Update the bootstrap checklist how-to to mention the section as an optional adoption item, not a required one.
5. Cross-check against AC2/AC6 wording so "absent or incomplete" and "no credentials" are unambiguous.

Testing Strategy:

• Unit Tests: covered by T-5's fixture set (complete / partial / absent infrastructure.md declarations).
• Integration Tests: none beyond the fixtures.
• Manual Testing: run assess-infrastructure against a fixture project to confirm it proposes the section without erroring when absent.

Notes: Keep the degraded (no declaration) path framed as first-class and permanent, not a placeholder — matches the story's "This is the extra" framing.

---

T-4: Implement assess-cost Step 9.2 matched path

Priority: P0 | Estimated Hours: 2h | Bounded Context: Development Collaboration

Summary: Rewrite pair-capability-assess-cost/SKILL.md Step 9.2 so the matched deploy-telemetry branch is a real, executable instruction set — dropping the "deferred… tracked by #399" note — while naming no provider inline (R2.13).

Type: Feature Implementation

Description: Current Step 9.2 (lines 130-132) states the contract then immediately marks it deferred with an explicit forward-reference to this story. Replace with: read the ## Cost & Billing Telemetry declaration from infrastructure.md; when present and complete, resolve the deploy match and billing delta by following T-2's guideline (named as a link, not inlined) for the exact API calls/semantics; when absent/incomplete, emit not available (unchanged, AC2); when a deployment cannot be found, emit not available with that specific reason (AC8); when the billing window is not yet consolidated, emit not available — billing window not yet consolidated (AC7); when multiple deployments match, apply the guideline's deterministic first-shipped rule (AC9). Also update the Output Format block (Deploy: line, currently hardcoded to "not available — no deploy telemetry declared (matched path deferred, #399)") and the Graceful Degradation section (line 264) to describe the now-permanent degraded branch without the "deferred" framing.

Acceptance Criteria:

• Primary deliverable: Step 9.2 rewritten; the word "deferred" removed from that step; assess-cost report mode — deploy/billing telemetry integration for deploy-match #399 self-reference removed (the story is being resolved, not deferred-to).
• Quality standard: no provider name (GitHub, AWS, Deployments, Cost Explorer, etc.) appears literally inside SKILL.md — only a link to T-2's guideline (R2.13, matches T-1's new assertion).
• Integration requirement: Output Format's Deploy: line and the Graceful Degradation bullet (line 264) updated consistently with the new step text.
• Verification method: T-1's assertions (a) and (b) now pass; T-1's assertion (c) (no inline provider name) passes.

Technical Requirements:

• Functionality: report mode never blocks regardless of match outcome (AC10) — explicitly preserved, not newly introduced.
• Performance: no change to the per-PR retain-and-discard context bound (Step 8) — deploy-match resolution happens per PR, same as today.
• Security: the skill instructs reading the declaration and calling out to the guideline's described APIs — it must not itself embed any credential-handling logic beyond "use the minimum read-only permission documented in the guideline".

Implementation Approach:

• Technical Design: minimal, surgical edit — Step 9.2's body, the Output Format Deploy: line, and the one Graceful Degradation bullet naming assess-cost report mode — deploy/billing telemetry integration for deploy-match #399/deferred.
• Bounded Context & Modules: .claude/skills/pair-capability-assess-cost/.
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md - Step 9.2, Output Format Deploy: line, Graceful Degradation bullet (edited as source).
• Technical Standards References:
  • .pair/knowledge/guidelines/quality-assurance/cost-assessment.md ("Layering" — skill applies rules, holds none)
  • This story's guideline (T-2) for the semantics the skill now points at

Dependencies:

• Technical: T-2 (guideline must exist to link to), T-3 (declaration shape must be documented consistently).
• Task Dependencies: T-2, T-3.
• Resource Dependencies: none.

Implementation Steps:

1. Rewrite Step 9.2's "Act" bullet to resolve the declaration and delegate API/semantics to T-2's guideline link.
2. Replace the "Status: the matched path is deferred…" paragraph with the now-real behavior description (including the AC7/AC8/AC9 distinct not available reasons).
3. Update the Deploy: line in Output Format (remove "(matched path deferred, assess-cost report mode — deploy/billing telemetry integration for deploy-match #399)").
4. Update the Graceful Degradation bullet (line 264) to drop "deferred until a telemetry integration lands (assess-cost report mode — deploy/billing telemetry integration for deploy-match #399, Step 9.2)".
5. Grep the file for any literal provider name and remove/replace with the guideline link.

Testing Strategy:

• Unit Tests: T-1's conformance assertions (must now pass).
• Integration Tests: T-5's fixture suite.
• Manual Testing: one recorded manual run against a project that has real deploy + billing telemetry, per the story's testing strategy — output attached to the story or PR, not asserted in CI.

Notes: No live billing/deploy API call is ever made from CI — this task changes the spec, T-5 changes the fixtures.

---

T-5: Fixture-driven tests for every panel-row branch

Priority: P1 | Estimated Hours: 2h | Bounded Context: Integration & Process Standardization

Summary: Add fixture-based conformance/unit coverage for each deploy-match outcome the panel can render, and confirm T-1's failing assertions now pass.

Type: Testing

Description: Per the story's Validation and Testing Strategy, build fixtures for: complete infrastructure.md declaration (matched), absent declaration, incomplete declaration, no deployment found (AC8), unconsolidated billing window (AC7), multiple deployments for the same commit (AC9), and the shared-service non-attributable case (edge case). No test may call a live billing/deploy API — all fixtures are static payloads. Also extend the AC11 conformance guard so both branches (matched + degraded) are asserted against the rewritten SKILL.md, replacing/augmenting T-1's initial minimal assertions with the full set.

Acceptance Criteria:

• Primary deliverable: fixture files/objects for the seven scenarios above, plus assertions per scenario.
• Quality standard: every scenario asserts the specific not available reason text is distinct where the story requires distinctness (AC2 vs AC7 vs AC8).
• Integration requirement: reuses assess-cost.test.ts's existing structure; no live network call anywhere in the suite.
• Verification method: pnpm vitest run green for the file; T-1's three assertions from earlier in this breakdown pass.

Technical Requirements:

• Functionality: each fixture scenario maps 1:1 to an AC or edge case named in the story.
• Performance: fixtures are small, static, in-tree — no runtime cost.
• Security: no credential fixture ever resembles a real secret shape (avoid false-positive secret-scan hits).

Implementation Approach:

• Technical Design: table-driven test cases, one fixture infrastructure.md declaration + one fixture deployment/billing payload per scenario.
• Bounded Context & Modules: packages/knowledge-hub/src/conformance/.
• Files to Modify/Create:
  • packages/knowledge-hub/src/conformance/assess-cost.test.ts - add the seven fixture scenarios; strengthen the AC11 both-branches assertion.
• Technical Standards References:
  • Story's "Validation and Testing Strategy" section (fixture list, no-live-API rule)
  • T-1's initial assertions (superseded/extended here)

Dependencies:

• Technical: T-4 (SKILL.md must describe each branch before fixtures can assert against it meaningfully).
• Task Dependencies: T-4.
• Resource Dependencies: none.

Implementation Steps:

1. Build the seven fixture declarations/payloads.
2. Write one assertion group per scenario, checking the exact not available — <reason> text distinctness (AC2/AC7/AC8).
3. Assert the multi-deployment fixture resolves via the deterministic first-shipped rule (AC9).
4. Re-run T-1's three assertions — confirm all now pass.
5. Run the full assess-cost.test.ts suite green.

Testing Strategy:

• Unit Tests: all seven scenarios, in-tree, no network.
• Integration Tests: none beyond the fixture-driven conformance suite (by design — matched-path realism is validated manually, not in CI).
• Manual Testing: n/a for this task (covered once, at T-4).

Notes: This is the task that turns T-1's red assertions green — keep the diff between T-1 and T-5 visible in the PR so the test-first sequence is auditable.

---

T-6: Register the guideline in the guidelines catalog

Priority: P2 | Estimated Hours: 1h | Bounded Context: Integration & Process Standardization

Summary: Add the new guideline to quality-monitoring/README.md's directory listing, to .pair/llms.txt, and to the docs site's guidelines catalog page.

Type: Documentation

Description: Per the DoD checklist bullet "Registered in the guidelines catalog + docs site". The quality-monitoring/README.md directory contents list currently names code-quality.md, performance-gates.md, observability-requirements.md — add the new file there. .pair/llms.txt lists each quality-monitoring/*.md file individually (lines ~404-407) — add the new entry in the same style. apps/website/content/docs/reference/guidelines-catalog.mdx is hand-maintained (not auto-derived from the dataset) — add a row/mention under the Quality Assurance category table.

Acceptance Criteria:

• Primary deliverable: three registrations (README, llms.txt, docs site mdx) all pointing at the same guideline file.
• Quality standard: matches the existing entry style in each of the three locations exactly (no format drift).
• Integration requirement: pnpm docs:staleness passes (no dead link, no stale count) after the addition.
• Verification method: run pnpm docs:staleness locally.

Technical Requirements:

• Functionality: link targets resolve (relative paths correct from each file's location).
• Performance: n/a.
• Security: n/a.

Implementation Approach:

• Technical Design: three small, mechanical edits, no content generation logic involved.
• Bounded Context & Modules: KB packaging/distribution (Integration & Process Standardization) for llms.txt/docs site; content listing itself is Knowledge & Standards' README.
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.pair/knowledge/guidelines/quality-assurance/quality-monitoring/README.md - add the new file to "Core Monitoring".
  • packages/knowledge-hub/dataset/.pair/llms.txt - add the new guideline entry (dataset copy; root .pair/llms.txt follows via mirror).
  • apps/website/content/docs/reference/guidelines-catalog.mdx - add a row under Quality Assurance.
• Technical Standards References:
  • apps/website/lib/docs-staleness-check.ts (the gate this registration must satisfy)

Dependencies:

• Technical: T-2 (file must exist to register).
• Task Dependencies: T-2.
• Resource Dependencies: none.

Implementation Steps:

1. Add the README.md list entry.
2. Add the llms.txt entry.
3. Add the docs site catalog row.
4. Run pnpm docs:staleness and fix any reported mismatch.

Testing Strategy:

• Unit Tests: none.
• Integration Tests: pnpm docs:staleness.
• Manual Testing: visually confirm the new row renders on the catalog page (local apps/website dev server), optional.

Notes: Purely mechanical — do this after T-2's content is stable to avoid re-editing three places if the filename changes.

---

T-7: Regenerate the KB mirror and verify the gate

Priority: P0 | Estimated Hours: 1h | Bounded Context: Integration & Process Standardization

Summary: Regenerate the installed KB mirror from the dataset source, run skills:conformance, and verify the story's 🟡 gate (lint + type + build + unit) is green.

Type: Configuration / Verification

Description: All content edits in T-2–T-6 happen in packages/knowledge-hub/dataset/.pair/... (dataset-as-source, per the DoD checklist). The installed mirror (.pair/... at repo root, .claude/skills/...) must be regenerated via pair update so the two stay identical (matching the existing pattern verified at the start of this breakdown, where cost-assessment.md was byte-identical in both locations). This is the closing verification task for the whole story: skills:conformance green confirms T-1/T-5's assertions pass against both dataset and mirror copies; the 🟡 gate (this story's classified tier) requires lint, type-check, build and unit tests green — no integration/E2E required at this tier.

Acceptance Criteria:

• Primary deliverable: mirror regenerated, dataset and installed copies identical for every file touched by T-2–T-6.
• Quality standard: pnpm skills:conformance exits 0.
• Integration requirement: pnpm turbo lint ts:check build test (or the project's quality-gate equivalent, 🟡-scoped subset) exits 0.
• Verification method: run each command and confirm exit codes; diff dataset vs. mirror copies of every touched file.

Technical Requirements:

• Functionality: mirror regeneration is idempotent — running it twice produces no further diff.
• Performance: n/a.
• Security: n/a.

Implementation Approach:

• Technical Design: run the existing pair update CLI flow against this checkout, then the existing gate scripts — no new tooling.
• Bounded Context & Modules: KB packaging & distribution pipeline (Integration & Process Standardization).
• Files to Modify/Create:
  • none directly — this task regenerates already-tracked mirror files (.pair/**, .claude/skills/**) from the dataset source edited in T-2/T-3/T-4/T-6.
• Technical Standards References:
  • .pair/adoption/tech/architecture.md ("Skills Distribution" — canonical target receives physical copies, secondary targets symlinks)

Dependencies:

• Technical: none beyond the CLI being buildable/runnable in this checkout.
• Task Dependencies: T-1, T-2, T-3, T-4, T-5, T-6 (all content and test changes land first).
• Resource Dependencies: none.

Implementation Steps:

1. Run pair update (or the repo-local equivalent) to regenerate the mirror from the dataset.
2. Diff dataset vs. mirror for every file touched in T-2/T-3/T-4/T-6 — confirm identical.
3. Run pnpm skills:conformance — confirm green (both branches asserted, T-1/T-5 pass).
4. Run the 🟡-tier gate subset (lint, ts:check, build, unit tests) — confirm green.
5. Record the manual out-of-tree verification (per the story's testing strategy) as a note on the PR, not as a CI assertion.

Testing Strategy:

• Unit Tests: pnpm --filter @pair/knowledge-hub test (includes assess-cost.test.ts).
• Integration Tests: none required at 🟡 tier.
• Manual Testing: the one out-of-tree manual run against a project with real telemetry, referenced by the story but not a CI gate item.

Notes: This task is the story's closing verification — it should be the last commit before publishing the PR.