Adoption-informed story generation (decision log + ADR + context map)

[rucka]

Story Statement

As a planner generating stories with pair
I want story generation to be adoption-informed — reading the project's decision log, ADRs, and context map so generated stories reflect actual project history and prior decisions
So that new stories don't contradict decisions already made or re-propose things already settled (R3.13)

Where: the existing story-generation flow — pair-process-plan-stories, pair-process-brainstorm (#230), and pair-process-refine-story — extended to read adoption context as input, not a new standalone skill

Epic Context

Parent Epic: Structured & parametrized brainstorming #205
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 project with a populated decision log / ADRs / context map
   When a story is generated (via pair-process-plan-stories or pair-process-brainstorm's triage phase)
   Then the generated story's content reflects those decisions — it does not re-propose a rejected approach, contradict an ADR, or ignore an established context-map term

2. Given a story being generated that touches an area covered by a prior decision
   When the generation flow runs
   Then it cites the relevant decision (ADR/ADL id or context-map entry) in the generated story, so the human sees why the story is shaped that way

3. Given a project with no adoption history yet (fresh project, empty decision log)
   When a story is generated
   Then generation degrades gracefully to today's behavior — no adoption context to read means no citations, never a failure (D21)

4. Given the same story generated twice with unchanged adoption
   When generation runs
   Then the adoption-informed input is applied deterministically — same decisions read, same influence on output

Business Rules

• Adoption-informed generation is a read-only input to generation — it never writes to the decision log or adoption files, only reads them (writing stays with the human / pair-capability-record-decision)
• Extension, not a new skill: the story-generation flow gains an adoption-reading step; no new capability is introduced (avoids a third place that reads adoption context)
• Reads the same adoption sources the rest of the KB already treats as authoritative: adoption/tech/adr/, adoption/decision-log/, and the context map (adoption/product/subdomain/*, adoption/tech/boundedcontext/*) per context-map.md + inline-update guideline (lazy subdomain contexts) #244's context-map artifact

Edge Cases and Error Handling

• Conflicting decisions in the log (a later decision supersedes an earlier one): generation follows the most recent / non-superseded decision, matching the ADR "Superseded by" convention
• Adoption files present but unparseable: warn and degrade to non-adoption-informed generation, never block (D21)
• A generated story genuinely needs to revisit a prior decision: it is allowed, but the generation flags it explicitly ("this revisits decision [id]") rather than silently contradicting it

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• The adoption-reading step is added to the story-generation flow (plan-stories, brainstorm triage, and/or refine-story) — SKILL.md updated for each touched skill
• Code review completed and approved
• Documentation updated — docs site (brainstorming / planning section)

Quality Assurance

• Dry-run: generate a story on a fixture project with a seeded decision log, confirm the output reflects and cites the decision; repeat on an empty-adoption fixture to confirm graceful degradation

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: Medium
Sizing Justification: extends 2-3 existing skills with a shared adoption-reading step; complexity is in defining what "informed by a decision" concretely means for generated output, not in new mechanism

Sprint Capacity Validation

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

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #230 (brainstorm — the primary generation flow this extends); #244 (context-map.md artifact — one of the adoption sources read), both same-epic/sibling-epic
Dependent Stories: none

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: hand-traced dry-run against a fixture project with a seeded decision log + context map (matching this session's established fixture-dry-run verification pattern for natural-language skills), plus an empty-adoption fixture for the degradation path
Test Data Requirements: a fixture .pair/adoption/ with at least one ADR, one ADL, and a context-map entry

Notes and Additional Context

Refinement Session Insights: 2026-07-11 — confirmed as an extension of the existing story-generation flow, not a new skill (the flow already reads other context; adoption history is one more input). Found during the epic-completeness audit as a planned R3.13 story that was never created.
Documentation Links: Requirements R3.13 · Spec G3 · pair-requirements-triage.md

Technical Analysis

Implementation Approach

Technical Strategy: add an adoption-context-reading step to the story-generation flow — the generating skill(s) read adoption/tech/adr/, adoption/decision-log/, and the context map before drafting, and factor them into the generated content + citations. No new skill file.
Key Components: pair-process-plan-stories, pair-process-brainstorm (triage phase), pair-process-refine-story — whichever actually author story content; the adoption-reading step is shared, described once and referenced
Integration Points: decision log / ADRs (pair-capability-record-decision's output), context map (#244)

Technical Requirements

• Read-only against adoption; deterministic; graceful degradation when adoption is empty/malformed

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
"Adoption-informed" is vague and each touched skill interprets it differently	Medium	Medium	Define the adoption-reading step once (single shared description), reference it from each skill rather than re-describing per skill
Reading full decision history bloats generation context on large projects	Low	Medium	Scope the read to decisions relevant to the story's subject/subdomain, not the entire log

Task Breakdown

Checklist

• T1 — Define the shared adoption-reading step (which sources, scoped to story subject, citation format, degradation)
• T2 — Wire it into the story-generation flow (plan-stories, brainstorm triage, refine-story as applicable)
• T3 — Fixture dry-run (seeded decision log → reflected+cited; empty adoption → graceful) + docs site update

Dependency Graph

T1 → T2 → T3

AC Coverage

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