pair-capability-checkpoint — resumable state (write/resume, handoff pattern)

[rucka]

Story Statement

As a developer working through long pair sessions
I want pair-capability-checkpoint: writes and resumes a self-contained progress state (story, branch, completed tasks, decisions, remaining todos) in .pair/working/checkpoints/ and/or the issue body
So that work survives context resets — a fresh session (or a subagent) resumes exactly where the previous one stopped (R2.10)

Where: .pair/working/checkpoints/ files + issue body section; consumed by implement and any composing skill

Epic Context

Parent Epic: Split implement: checkpoint + publish-pr #206
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 an in-progress story with completed and pending tasks
   When checkpoint is invoked in write mode
   Then a checkpoint document is produced containing story id, branch, tasks done, key decisions, remaining todos — readable by a session with zero prior context

2. Given an existing checkpoint for the current story
   When checkpoint is invoked in resume mode
   Then it returns the parsed state (story, branch, done/pending tasks, decisions) so the caller continues without repeating completed work

3. Given a write invocation while a checkpoint already exists
   When the new state is saved
   Then the checkpoint is updated in place (one checkpoint per story), not duplicated

4. Given a caller requesting the checkpoint as a handoff prompt
   When write mode completes
   Then the checkpoint text is returned to the caller (write-free composition allowed: the composer decides where it lands)

Business Rules

• Checkpoint format is a documented KB convention (template): fresh-session readability is the acceptance bar
• Default location .pair/working/checkpoints/<story-id>.md; issue-body mirror optional
• Based on the handoff pattern: synthesis of state into a transition document (D8)
• Checkpoints are operational files: never touched by install/update (D14 — enforced by sibling story)

Edge Cases and Error Handling

• No story context detectable: HALT asking the caller to pass the story id
• Corrupted/incomplete checkpoint on resume: report what was parsed, ask confirmation before proceeding
• Multiple checkpoints found for one story: use most recent, flag the duplicates

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Skill follows authoring conventions
• Code review completed and approved
• Documentation updated — docs site (apps/website) page for the new capability
• CLI (apps/pair-cli) unaffected verified (no distribution change in this story)

Quality Assurance

• Fresh-session resume test: checkpoint written by one session, resumed by a clean one (dogfood)
• Idempotent update verified (write twice, one file)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: High
Sizing Justification: single capability, well-known handoff pattern, no external integrations; format design is the main effort

Sprint Capacity Validation

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

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none (enabling primitive)
Dependent Stories: publish-pr story (handoff input), implement composition story, future supervisor loop (#212)
Shared Components: .pair/working/ area (sibling P1 story handles registry exclusion)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: scripted session pairs (write → clean-context resume); checkpoint fixture review against template
Test Data Requirements: sample story mid-implementation (tasks partially done)

Notes and Additional Context

Refinement Session Insights: write-free return option mirrors A8 (grill): the composer owns persistence
Documentation Links: R2.10, R4.1 · Spec G5 · D8, D14

Technical Analysis

Implementation Approach

Technical Strategy: new capability skill in .skills/capability/checkpoint/; two modes (write/resume) selected by argument or context; checkpoint template in KB (collaboration/templates/ or skill-local reference); default path under .pair/working/checkpoints/
Key Components: SKILL.md (modes, HALT rules), checkpoint template, resume parser instructions
Integration Points: implement (both modes), publish-pr (consumes as handoff), future supervisor

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Checkpoint too thin to resume reliably	High	Medium	template mandates the five state sections; fresh-session test in QA
Divergence file vs issue-body mirror	Low	Medium	file is source of truth; mirror explicitly marked as copy

Task Breakdown

Checklist

• T1 — Checkpoint template (five sections) + KB placement
• T2 — SKILL.md write mode (gather state, write/update file, optional return-to-caller)
• T3 — SKILL.md resume mode (locate, parse, report state; edge cases)
• T4 — Fresh-session dogfood test + docs site page

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

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

---

T-1: Checkpoint template (five sections) + KB placement

Priority: P0 | Estimated Hours: 2h | Bounded Context: Collaboration Templates (Knowledge Base)

Summary: Author checkpoint-template.md — the five state sections (Story, Branch, Tasks Done, Key Decisions, Remaining Todos) plus an authoring-only Template Notes section — and register it in the templates catalog.

Type: Documentation

Description: Created checkpoint-template.md under packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/ with a header (story id/title, Last updated, Written by), a "read top to bottom" framing line, the five numbered sections with bracket placeholders matching the SKILL.md's Step 5/Step 7 contract, and a trailing "Template Notes" section documenting file location, source-of-truth, resume-parsing, and unknown-state conventions. Registered the template in templates/README.md (Quick Reference table row + a bullet under "Development Process Templates").

Acceptance Criteria:

• Primary deliverable: checkpoint-template.md with the 5 required sections + Template Notes — done.
• Quality standard: consistent header/footer style with sibling templates (e.g. manual-test-case-template.md) — done.
• Integration requirement: template registered in templates/README.md catalog (table row + prose bullet) — done.
• Verification method: manual review; cross-check against SKILL.md's references to the template path — done.

Implementation Approach:

• Technical Design: static Markdown template with bracket placeholders, no executable code.
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md - new template (5 sections + Template Notes)
  • packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/README.md - catalog registration (table row, "Development Process Templates" bullet)

Dependencies:

• Tasks: none (root task; T2 depends on this)

Implementation Steps:

1. Draft the five required sections with bracket placeholders, matching the state model referenced by SKILL.md Steps 3 and 7.
2. Add the "Template Notes" section documenting file location, source-of-truth, resume-parsing, and unknown-state conventions.
3. Register the template in README.md's Quick Reference table and "Development Process Templates" list.
4. (fix commit c008aa4) Add an explicit "omit from rendered checkpoints" disclaimer at the top of Template Notes, closing a parse ambiguity — see T-3 Notes.

Testing Strategy:

• Unit Tests: N/A — pure documentation artifact, no executable code.
• Manual Testing: visual review of the rendered template against the section contract SKILL.md's write/resume steps assume.

Notes: Real gap found and closed within the branch itself: as first written (dd7c775), Template Notes had no explicit marker excluding it from rendered checkpoint output, which is exactly the ambiguity that produced the resume-parsing bug described in T-3. The fix commit (c008aa4) added the disclaimer here and taught the parser (Step 7) to ignore a trailing 6th section. In the current (fixed) state, T-1's deliverable fully matches its Acceptance Criteria — no open gap.

---

T-2: SKILL.md write mode (gather state, write/update file, optional return-to-caller)

Priority: P0 | Estimated Hours: 4h | Bounded Context: Capability skill (.skills/capability/checkpoint/)

Summary: Implement write mode: resolve story context, gather state (from session or reconstructed from git/PM-tool/ADR artifacts), detect an existing checkpoint, and render + persist (or write-free return) the checkpoint text.

Type: Feature Implementation

Description: SKILL.md defines the write path as Steps 1 (resolve $story), 2 (route by $mode), 3 (gather state — direct from session context, or reconstructed via git branch --show-current, the story's Task Breakdown checklist cross-referenced with branch commits, and a scan of adr//decision-log/ files touched since the branch diverged), 4 (detect an existing checkpoint file and flag stray duplicates, using the most recently modified as base), and 5 (render via the template and either write to .pair/working/checkpoints/<story-id>.md or, if $persist=false, return the text without touching the filesystem). The Core Rule section states the one-file-per-story invariant explicitly. Output Format defines the "CHECKPOINT WRITTEN" report block.

Acceptance Criteria:

• Primary deliverable: Steps 1–5, Core Rule, Arguments table ($mode/$story/$persist), and Output Format for write mode — done.
• Quality standard: procedural Check/Act/Skip/Verify structure per step, consistent with the file's own resume-mode steps — done.
• Integration requirement: supports both full-context (session-known state) and no-context reconstruction paths, plus write-free ($persist=false) composition for future composers — done.
• Verification method: manual write-twice dry run (see Testing Strategy).

Implementation Approach:

• Technical Design: argument-driven procedural algorithm authored as Markdown instructions for an LLM (no executable code — this is a KB-shipped capability skill).
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md - new skill file: frontmatter, Arguments, Core Rule, Steps 1–5, Output Format ("CHECKPOINT WRITTEN")

Dependencies:

• Tasks: T-1 (write mode renders against the checkpoint template)

Implementation Steps:

1. Define frontmatter (name/description/version/author) and the Arguments table ($mode, $story, $persist).
2. Write Step 1 (resolve story context, HALT if undetectable) and Step 2 (route by mode).
3. Write Steps 3–5: gather/reconstruct state, detect + dedupe existing checkpoint, render and persist-or-return per $persist.
4. Define the "CHECKPOINT WRITTEN" Output Format block (story/branch/path/mode/tasks summary).

Testing Strategy:

• Unit Tests: N/A — no executable code; this is an instruction-following skill for an LLM agent, not a unit-testable module.
• Manual Testing: the implementer reported performing a real write-twice idempotency check in a scratch session — writing the same story's checkpoint twice and confirming the file was updated in place rather than duplicated. Not committed to the repo, since files under .pair/working/ are operational/runtime artifacts excluded from KB-shipped content per D14.

Notes: No functional gap between this task's Acceptance Criteria and the shipped SKILL.md content. One transparency caveat: the write-twice verification is done-but-not-persisted-as-a-fixture (correctly, per D14) rather than untested — but it also means there is no repo-visible evidence artifact for an independent reviewer to inspect; it rests on the implementer's report.

---

T-3: SKILL.md resume mode (locate, parse, report state; edge cases)

Priority: P0 | Estimated Hours: 3h | Bounded Context: Capability skill (.skills/capability/checkpoint/)

Summary: Implement resume mode: locate the single checkpoint file for a story, parse its five state sections while ignoring the authoring-only Template Notes appendix, and report the parsed state — with explicit edge-case handling for missing, corrupted, or duplicate checkpoints.

Type: Feature Implementation

Description: SKILL.md Steps 6–8 cover locating .pair/working/checkpoints/<story-id>.md (HALT if none found; most-recently-modified wins and others are flagged if duplicates resolve to the same story), parsing the five sections top to bottom (Story, Branch, Tasks Done, Key Decisions, Remaining Todos) without guessing at missing/malformed data, and reporting the result via the "CHECKPOINT RESUMED" output block. The Edge Cases section cross-references Steps 1, 4/6, and 7 for the no-context, duplicate, and corrupted-checkpoint scenarios respectively.

Acceptance Criteria:

• Primary deliverable: Steps 6–8 (locate/parse/report) and the Edge Cases section — done.
• Quality standard: never fills gaps by guessing; malformed/missing sections are reported explicitly and confirmation is requested — done.
• Integration requirement: parsing correctly distinguishes the 5 state sections from the trailing Template Notes appendix — done, but only after an in-branch fix (see Notes).
• Verification method: fresh-session resume dry-run (see Testing Strategy / T-4).

Implementation Approach:

• Technical Design: same procedural Check/Act/Skip/Verify style as write mode, authored as Markdown instructions.
• Files to Modify/Create:
  • packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md - Steps 6–8, Edge Cases section, "CHECKPOINT RESUMED" Output Format block

Dependencies:

• Tasks: T-2 (resume mode reads against the same one-file-per-story contract and template shape that write mode establishes)

Implementation Steps:

1. Step 6: locate the checkpoint file; HALT with an explicit message if none exists; flag duplicates and select the most recently modified if multiple resolve to the same story.
2. Step 7: parse the five sections in order; never guess on missing/malformed sections — report exactly what parsed and ask for confirmation instead.
3. Step 8: render the "CHECKPOINT RESUMED" report (story, branch, tasks done/left, decisions, confidence).
4. Document the Edge Cases section, cross-referencing the relevant steps for each scenario.

Testing Strategy:

• Unit Tests: N/A — no executable code.
• Manual Testing: the implementer reported a real fresh-session resume dry-run — a checkpoint written in one session and its resume/parse verified in a separate, clean-context session. Not committed as a fixture (operational file under .pair/working/, excluded from KB-shipped content per D14); done-but-not-persisted, not untested.

Notes: Real gap found and fixed within this same branch: as first written (dd7c775), Step 7's parse instruction ("Parse the five sections in order") did not say what to do about the Template Notes section, which — once it got its own explicit heading in the template — reads structurally like a plausible 6th section. A resume parse following the original instruction literally could have flagged it as unexpected/malformed content instead of ignoring it. The fix commit (c008aa4) closed this by (a) adding "Ignore a trailing 'Template Notes' (or any 6th) section if one is present — it is authoring guidance, not checkpoint state" to Step 7, and (b) adding the matching disclaimer to the template itself (see T-1). This is precisely the kind of implementation/spec mismatch this verification pass exists to catch; it was caught and fixed in-branch before this documentation was written. No remaining open gap for T-3 in the current state of the branch.

---

T-4: Fresh-session dogfood test + docs site page

Priority: P0 | Estimated Hours: 2h | Bounded Context: QA / Docs site (apps/website)

Summary: Validate the write→resume handoff end-to-end (fresh-session resume + write-twice idempotency) and publish the capability in the public skills catalog.

Type: Testing, Documentation

Description: Two deliverables. (1) Manual verification: a fresh-session resume test (checkpoint written by one session, correctly parsed by a separate clean-context session) and an idempotent-update check (writing the same story's checkpoint twice results in one file, updated in place). (2) apps/website/content/docs/reference/skills-catalog.mdx updated: skill count bumped 33 → 34, "Last updated" date bumped to 2026-07-06, and a new "State and Handoff Capabilities" table section added listing checkpoint (/pair-capability-checkpoint) with its one-line description.

Acceptance Criteria:

• Primary deliverable: docs site catalog entry — done, verified in diff. Dogfood/idempotency verification — reportedly done, not committed as a fixture (see Notes).
• Quality standard: docs entry matches the existing catalog table format and style — done.
• Integration requirement: the new skill is documented under a coherent new category ("State and Handoff Capabilities") rather than shoehorned into an unrelated existing section — done.
• Verification method: manual review of the rendered .mdx table; manual dogfood test performed in a scratch session (not committed).

Implementation Approach:

• Technical Design: direct edit to the existing static catalog page; the dogfood test is manual/interactive (no automated harness exists for KB-authored skills in this repo).
• Files to Modify/Create:
  • apps/website/content/docs/reference/skills-catalog.mdx - skill count (33→34), "Last updated" date, new "State and Handoff Capabilities" table section with the checkpoint row

Dependencies:

• Tasks: T-1, T-2, T-3 (must exist before they can be dogfooded and documented as shipped)

Implementation Steps:

1. Perform a write-mode dry run for a real/sample story, producing a checkpoint file under .pair/working/checkpoints/.
2. In a separate, clean-context session, invoke resume mode against that same file; confirm all five sections parse cleanly and the reported state matches what was written.
3. Re-invoke write mode a second time for the same story; confirm the file is updated in place (same path, one file) rather than duplicated.
4. Update skills-catalog.mdx: bump the skill count and "Last updated" date, add the "State and Handoff Capabilities" section with the checkpoint row.

Testing Strategy:

• Unit Tests: N/A — no executable code.
• Manual Testing: fresh-session resume test and write-twice idempotency check both reportedly executed by the implementer in a scratch/ad-hoc session. Results were not persisted as a committed fixture, per D14 (.pair/working/ operational files are excluded from KB-shipped content, so there is no natural committed home for a sample checkpoint either). Done-but-not-persisted-as-a-fixture, not untested.

Notes: Real discrepancy to flag: the issue's Definition of Done checklist still shows both QA items unchecked — "Fresh-session resume test: checkpoint written by one session, resumed by a clean one (dogfood)" and "Idempotent update verified (write twice, one file)" — while the manual testing described above (and reflected in T-2/T-3 Notes) indicates both were actually performed. This documentation pass does not modify the DoD checklist (out of scope per instructions), but whoever closes out story #254 should either check those boxes with a note on how they were verified, or re-run and capture evidence before merge. The docs-site catalog update itself (skill count, date, new table section) is fully verified in the diff — no gap there.