Architecture quality: coupling-balance guideline + assess-coupling (diff/full) in review

[rucka]

Story Statement

As a development team
I want coupling evaluated with an explicit three-dimensional model (integration strength, distance, volatility + balance rule) — on the PR diff during review and full-scope as a codebase audit via pair-capability-assess-coupling
So that architecture quality (R7.5) is measurable and reviewable: unbalanced coupling in volatile areas is caught before merge, and architectural debt is tracked instead of accumulating silently

Where: review report on the PR (Architecture verdict line) + .pair/working/reports/architecture/ (full audit) + tech-debt backlog items

Epic Context

Parent Epic: Code Quality & Testing foundations #209
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

Description

Deliverables:

1. Guideline knowledge/guidelines/architecture/design-patterns/coupling-balance.md — the model, written as original Pair content: three dimensions — integration strength (how much knowledge two components share, four levels: intrusive > functional > model > contract), socio-technical distance (cost of co-evolving: code structure, team boundaries, runtime dependencies), volatility (probability of change, evaluated from the business domain via subdomain classification, never from commit history alone — essential vs accidental volatility); the balance rule: coupling is unbalanced when strength and distance are both high (cascading, expensive changes) or both low (low cohesion); low volatility neutralizes an imbalance. Pathological combinations, severity criteria, mapping to the DDD patterns already in KB (bounded contexts, anti-corruption layer, open-host, aggregates), fractal application at every abstraction level. Test implications: contract-coupled relationships imply integration contract tests (the contract is honored) and boundary tests (encapsulation holds — nothing leaks). Bibliographic reference to coupling.dev.
2. pair-capability-assess-coupling with $scope: diff | full (same pattern as assess-cost/assess-security):
   • diff: only the integrations touched by the PR — shared knowledge and strength level, distance, volatility (read from adoption/product/subdomain/ and adoption/tech/boundedcontext/ when present, otherwise asked/estimated) → balance verdict, 1 line + findings with severity.
   • full: codebase audit — maps integrations between components, flags only unbalanced and volatile ones, findings become tech-debt items (Tech-debt backlog #224 pipeline) + report in .pair/working/reports/architecture/.
   • Always reads the actual code (imports, calls, shared data structures, data access), never structure alone. Never recommends blanket decoupling: decomposition raises distance, so it is only suggested when strength is low enough to support it.
3. process/review step 2.3 extended: invokes assess-coupling $scope: diff; "Architecture" verdict-first row in the report (Extended code-review template (security + cost, reading budget) #228); critical severity → major/critical finding in the existing severity flow; capability absent → "not assessed".
4. assess-architecture: the guideline joins the readings of its evaluation step (coupling criteria inform pattern scoring).

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a PR whose diff introduces a strong integration (functional/model level) between distant components in a volatile area
   When review runs step 2.3
   Then the Architecture row reports a finding with severity and a rebalancing proposal grounded in the model — reduce strength (introduce a contract) or reduce distance (co-locate), never a single-dimension "decouple" recommendation

2. Given the same unbalanced integration in a low-volatility area
   When review runs
   Then a tech-debt item is created (Tech-debt backlog #224 pipeline) and the PR is NOT blocked

3. Given a project with no subdomain/boundedcontext artifacts
   When assess-coupling $scope: full runs
   Then volatility is asked/estimated (no-DDD degradation), the audit completes, and only unbalanced+volatile integrations are flagged

4. Given the review report
   When the reviewer reads it
   Then the Architecture verdict is 1 line at the top with details collapsed (~30s read, D22); if the capability is absent the row states "not assessed"

5. Given the KB after implementation
   When searched for the model content
   Then it lives ONLY in the guideline (skills reference it, never duplicate it) and contains no third-party text (original wording)

Business Rules

• Coupling is always evaluated on all three dimensions; a finding grounded in fewer than three is invalid
• Severity: critical = unbalanced + high volatility; significant = unbalanced + moderate volatility, or implicit shared knowledge (duplicated business rules, private-interface access); tolerable = unbalanced + low volatility → tech-debt, never blocks
• Volatility defaults from subdomain classification (core → high, supporting → medium, generic → low functional / provider-dependent implementation volatility); commit frequency alone is never evidence
• Distance is relative to the abstraction level under analysis (fractal): cross-module imbalance counts even inside a single deployable
• The assessment reads real integration points; structure-only findings are not allowed

Edge Cases and Error Handling

• Huge diff: assessment scoped to changed integration points only, never the whole codebase in diff mode
• No DDD artifacts: ask/estimate volatility; never HALT (consistent with map-subdomains/map-contexts reclassified process→capability (scoped, callers matrix) #246 degradation)
• Capability absent in review: "not assessed" row, review proceeds (standard graceful degradation)
• Single-module project: no cross-component integrations → verdict "balanced / not applicable", no noise findings

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Guideline written as original content (zero third-party text), bibliographic reference included
• Skill follows authoring conventions (resolution cascade, graceful degradation, composition)
• Code review completed and approved
• Docs site (apps/website) updated: guideline page + assess-coupling skill page + review flow update
• CLI (apps/pair-cli): new guideline + skill distributed via existing registries (verify install/update picks them up)

Quality Assurance

• Dogfood: assess-coupling $scope: full run on the pair repo itself; findings triaged
• Diff mode verified on a real PR (balanced and unbalanced scenarios)
• Degradation paths verified (no DDD artifacts; capability absent in review)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5
Confidence Level: Medium
Sizing Justification: one guideline + one capability (two modes) + two skill extensions; same shape and weight as assess-security (#227 = 5)

Sprint Capacity Validation

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

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #228 (Architecture row slots into the extended review template); #224 (tech-debt item pipeline for full-audit findings)
Soft dependencies (degradable): #221 (taxonomy entry "architecture/modularity" under Delivery points to the guideline); #246 (subdomain Volatility field as input — assess-coupling asks/estimates when absent)
Dependent Stories: none

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: scripted review sessions on PRs with known coupling profiles (strong+distant+volatile; strong+distant+stable; balanced); full audit dogfood on pair repo; no-DDD project fixture
Test Data Requirements: sample diffs introducing cross-context integrations; project fixture without subdomain/boundedcontext files

Notes and Additional Context

Refinement Session Insights: D36 (original reimplementation, no external plugin composition), D37 (model lives in ONE guideline), D38 (consumers: map-* templates, review diff, full audit, risk classification), D39 (this story fills the R7.5 slot; no new epic)
Documentation Links: R7.5 · modularity-pair-triage.md MG1 · D22 (reading budget), D24 (capability rule: 2 callers)

Technical Analysis

Implementation Approach

Technical Strategy: new guideline file in dataset KB; new capability skill .skills/capability/assess-coupling/SKILL.md referencing the guideline (never inlining it); process/review SKILL.md step 2.3 extended with composition + degradation; assess-architecture SKILL.md reading list extended; report template for .pair/working/reports/architecture/
Key Components: guideline (model, severity, DDD mapping); SKILL.md with $scope contract; review composition point; docs site pages
Data Flow: subdomain/boundedcontext (volatility, boundaries) → assess-coupling → verdict/findings → review report row + tech-debt items + working report
Integration Points: process/review (step 2.3), assess-architecture, #224 assess-debt pipeline, #228 report template

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Noisy findings (flagging everything)	High	Medium	flag only unbalanced+volatile; severity gate; "few critical > many minor" rule in skill
Wording too close to third-party sources	High	Low	original-content check in code review (AC5); concepts only, own examples
Volatility estimation arbitrary without DDD artifacts	Medium	Medium	explicit ask with defaults-from-classification heuristic; estimate labeled as such in report

Task Breakdown

Checklist

• T1 — Guideline coupling-balance.md (model, severity criteria, DDD mapping, bibliography)
• T2 — pair-capability-assess-coupling SKILL.md: $scope: diff|full, volatility sourcing + degradation, verdict/findings format
• T3 — process/review step 2.3 extension: composition, Architecture row, "not assessed" degradation
• T4 — assess-architecture reading-list extension
• T5 — Full-audit output: report template + tech-debt item creation via Tech-debt backlog #224 pipeline
• T6 — Docs site pages (guideline, skill, review flow) + distribution check (CLI registries)
• T7 — Validation: dogfood full audit on pair repo + scripted diff scenarios + degradation paths

Dependency Graph

T1 → T2 → (T3 ∥ T4 ∥ T5) → T6 → T7

AC Coverage

Task	AC1	AC2	AC3	AC4	AC5
T1					✓
T2	✓	✓	✓		✓
T3	✓			✓
T4					✓
T5		✓	✓
T6				✓
T7	✓	✓	✓	✓	✓