pair-capability-assess-cost — multi-provider cost class at review

[rucka]

Resolution

Delivered by PR #361 (merged). Board: Done.

feat: pair-capability-assess-cost — multi-provider cost class at review.

Story Statement

As a reviewer or developer opening a PR
I want pair-capability-assess-cost: a generic, multi-provider cost classification (green/low/medium/red) shown at review time
So that the cost dimension of every change is assessed with an objective criterion (R6.1) and feeds the classification matrix

Where: review report / PR (1-line class + <details>); standalone invocation for ad-hoc assessment

Epic Context

Parent Epic: Unified classification & assessments #208
Status: Refined
Priority: P0 (Must-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 story or PR diff introducing infrastructure/service load (e.g., new queue, cron, storage)
   When assess-cost runs
   Then it outputs a class among green/yellow/orange/red (chromatic, Q2) with a 1-line rationale and a <details> breakdown, applying the guidelines heuristics selected by the project stack/architecture/infrastructure adoption files (decision Q3)

2. Given the KB guidelines contain general cost heuristics + AWS-specific ones (decision Q3)
   When assess-cost runs on a project whose adoption declares AWS
   Then AWS heuristics apply; other providers via adoption links (fallback/extension, no skill change)

3. Given a PR under review
   When pair-process-review runs
   Then the cost section shows the class in 1 line at the top with details collapsed (D22)

4. Given no cost-relevant change in the diff
   When assess-cost runs
   Then class = green with rationale "no cost surface touched"

Business Rules

• Heuristics live in KB guidelines (general + per-provider, starting with AWS); the analysis is driven by tech-stack.md / architecture.md / infrastructure.md adoption; adoption links = fallback for other providers (Q3). Never inside the skill (D17/D21)
• Output = cost dimension of the classification matrix; consumed by classify, never interpreted by the skill itself
• Provider-agnostic core: adding a provider touches adoption/KB only (R2.13)

Edge Cases and Error Handling

• Unresolvable cost surface (unknown tech): class = medium + explicit "unknown surface" flag (conservative, visible)
• Missing quality model: HALT with pointer to install/bootstrap (model is prerequisite)
• Report mode with no closed PRs: empty report generated, no error

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Skill follows skill-authoring conventions (frontmatter, arguments, HALT conditions, composition interface)
• Code review completed and approved
• Documentation updated — docs site page for the capability
• Distribution: skill present in .claude/skills outputs via knowledge-hub transfer

Quality Assurance

• All acceptance criteria tested (green/low/medium/red sample diffs)
• Composition with review verified; standalone invocation verified

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Medium
Sizing Justification: new capability + review integration + guidelines heuristics (general + AWS); report mode (monitoring/panel) EXCLUDED (separate ② story)

Sprint Capacity Validation

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

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #221 quality model doc (cost classes + heuristics live there)
Dependent Stories: classify (cost dimension), cost monitoring + panel (report mode, slice ②)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: fixture diffs per class; review composition dry-run on a real pair PR
Test Data Requirements: 4 sample changes (one per class) + one unknown-surface change

Notes and Additional Context

Refinement Session Insights: report/monitoring mode (R6.3/R6.4) deliberately split to slice ② — this story is assessment-at-review only
Documentation Links: spec G7; D14, D17, D21, D22

Technical Analysis

Implementation Approach

Technical Strategy: new capability skill following the assess-* cascade; reads tech-stack/architecture/infrastructure adoption to select guideline heuristics (general + provider-specific, AWS first); review SKILL.md updated to compose it
Key Components: SKILL.md (algorithm, arguments $scope, $diff|$story, output format); quality model cost section; review composition hook
Integration Points: pair-process-review Phase 2; classify (dimension input); adoption cost links

Technical Requirements

• Output machine-readable (class token) + human 1-line (D22)
• No provider names hardcoded in the skill

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Heuristics too generic → everything "medium"	Medium	Medium	calibrate on real pair PRs during QA; unknown-surface flag keeps honesty

Task Breakdown

Checklist

• T1 — Author pair-capability-assess-cost SKILL.md (cascade, args, output, HALT)
• T2 — Extend KB guidelines: general cost heuristics + AWS-specific (infrastructure/cloud-providers); classes in quality model; adoption-link fallback mechanism
• T3 — Compose in pair-process-review (cost section, 1-line + details)
• T4 — Fixtures + QA on sample diffs; docs site page; distribution transfer

Dependency Graph

T2 → T1 → T3 → T4

AC Coverage

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

Addendum — spec integrations (2026-07-06)

• Cost-signal catalog (in the guideline, scanned on the diff): paid-SDK imports (payment/LLM/messaging providers), API-key env vars, IaC/provisioning changes, cron/scheduled jobs, queues/pipelines, media processing, LLM calls. Highest signal ⇒ class on the A2 4-level scale (cost:green|yellow|orange|red).
• Red class ⇒ blocking human sign-off (consistent with explicit approval in the G6 flow): the PR cannot proceed on cost grounds until a human signs off.
• Review output stays within reading budget (D22): 1 verdict line + <details> with detected signals table.
• Guideline includes a "cost gotchas" section (non-obvious cost patterns).