pair-capability-assess-cost report mode — cost monitoring + consolidated panel

[rucka]

Story Statement

As a team using pair
I want pair-capability-assess-cost's report mode — bidirectional cost monitoring (predicted vs. real on closed PRs, deploy match) plus a consolidated panel in .pair/working/reports/
So that predicted-vs-actual cost drift and cost exposure across the project are visible in one place (R6.3, R6.4)

Where: pair-capability-assess-cost's report mode (slice ②, distinct from its review-time classification mode #226); output in .pair/working/reports/

Epic Context

Parent Epic: Unified classification & assessments → tags #208
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a set of closed PRs each carrying a refinement-time predicted cost class
   When assess-cost runs in report mode over a period
   Then it produces a bidirectional monitoring view: predicted cost class vs. real/observed cost signals per PR, flagging drift (predicted green but real red, etc.) (R6.3)

2. Given the monitored PRs and their cost data
   When report mode completes
   Then it renders a consolidated panel (markdown) into .pair/working/reports/ — a headline summary + collapsed per-PR/per-category breakdown, following the same reports-area conventions AI metrics & retro reports (bug resolution, PR lead time, adoption) #222 (AI metrics) shares (R6.4)

3. Given report mode is re-run for the same period
   When it completes
   Then the panel for that period is updated in place (idempotent by period key), not duplicated — same reports-area convention as AI metrics & retro reports (bug resolution, PR lead time, adoption) #222

4. Given a project with no cost data yet, or cost tagging not activated (Tag Projection opt-in per Quality model document (3 layers + 3 pillars + default classification rules + taxonomy) #221)
   When report mode runs
   Then it reports "no cost data for this period" gracefully rather than failing — cost monitoring depends on cost having been assessed, and says so if it wasn't

Business Rules

• Report mode is a mode of pair-capability-assess-cost, not a new skill — pair-capability-assess-cost — multi-provider cost class at review #226 (assess-cost review-time classification) explicitly excludes report mode and lists it as this separate ② story; both modes live in the same skill
• Writes only to .pair/working/reports/ (operational area, D14, excluded from KB install/update per .pair/working/ excluded from KB registries + adoption path override #257) — never to adoption or issues
• Report/panel generation shares the period/idempotency convention with AI metrics & retro reports (bug resolution, PR lead time, adoption) #222 (AI metrics reports) — one reports-area pattern, not two
• Cost classification itself is not redefined here — report mode consumes the cost class produced by pair-capability-assess-cost — multi-provider cost class at review #226's review-time assessment and by the quality model (Quality model document (3 layers + 3 pillars + default classification rules + taxonomy) #221 §3.3); it aggregates and compares, it does not re-derive criteria

Edge Cases and Error Handling

• Predicted cost missing on some PRs (classified before cost tagging was active): report those PRs as "no prediction — real only", never drop them silently
• .pair/working/reports/ not writable: degrade to presenting the panel inline and telling the human to save it, same pattern as other reports-area writers
• Deploy-match data unavailable (no deploy telemetry integration): the deploy-match dimension reports "not available" explicitly rather than fabricating a match

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• assess-cost SKILL.md extended with report mode ($mode: report or equivalent), distinct from its classification mode
• Code review completed and approved
• Documentation updated — docs site (cost assessment / reports section)

Quality Assurance

• Dry-run: report mode over a fixture set of closed PRs with seeded predicted-vs-real cost data, confirm drift flagging + panel rendering + in-place idempotent re-run

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: Medium
Sizing Justification: report mode on top of the classification mode #226 already establishes; shares the reports-area pattern with #222, so the generation/idempotency mechanics are not net-new

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #226 (assess-cost classification mode — report mode consumes its cost class); #221 (quality model, cost class §3.3 — merged); #257 (working-area exclusion — reports land there); soft-shares the reports-area convention with #222
Dependent Stories: #222 (AI metrics) explicitly names this story as a prerequisite for the shared reports-area conventions

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: fixture dry-run over a seeded set of closed PRs with predicted-vs-real cost data (matching this session's fixture-dry-run pattern); idempotency re-run check
Test Data Requirements: fixture closed PRs with predicted cost classes + observed cost signals

Notes and Additional Context

Refinement Session Insights: 2026-07-11 — found during the epic-completeness audit; #226's own body already carved this out ("report mode (monitoring/panel) EXCLUDED — separate ② story") and #222 lists it as a prerequisite, but the story itself was never created. Confirmed as assess-cost's report mode, sharing the reports-area convention with #222.
Documentation Links: Requirements R6.3, R6.4 · Spec G6/G7 · Decision D14 · pair-requirements-triage.md

Technical Analysis

Implementation Approach

Technical Strategy: add a report mode to pair-capability-assess-cost that (1) pulls closed PRs for a period from the PM tool / code host, (2) compares each PR's refinement-time predicted cost class against real/observed cost signals, (3) renders a consolidated markdown panel into .pair/working/reports/, idempotent by period key — reusing the reports-area generation/idempotency convention shared with #222
Key Components: assess-cost SKILL.md (report mode); reports-area panel template; period/idempotency convention (shared with #222)
Integration Points: #226 (cost class source), #222 (shared reports-area convention), #257 (working-area location)

Technical Requirements

• Report mode is read-only except for the single reports-area file it writes; idempotent by period; graceful when cost data is absent

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
"Real/observed cost" requires deploy/billing telemetry pair doesn't own	Medium	High	Deploy-match/real-cost dimensions degrade to "not available" explicitly when no telemetry integration exists; predicted-vs-predicted-at-review is always available as the baseline comparison
Reports-area convention diverges from #222's if built independently	Low	Medium	Coordinate the shared period/idempotency/panel convention with #222; whichever lands first defines it, the other reuses

Task Breakdown

Checklist

• T1 — Define report mode: period selection, predicted-vs-real comparison, drift flagging, degradation when data absent
• T2 — Consolidated panel rendering into .pair/working/reports/, idempotent by period (shared convention with AI metrics & retro reports (bug resolution, PR lead time, adoption) #222)
• T3 — Fixture dry-run (seeded predicted-vs-real over closed PRs) + idempotency re-run + docs site update

Dependency Graph

T1 → T2 → T3

AC Coverage

Task	AC1	AC2	AC3	AC4
T1	✓			✓
T2		✓	✓
T3	✓	✓	✓	✓