From b2069019955254049111d36897c2427ae54fae4a Mon Sep 17 00:00:00 2001 From: YiChu Date: Sun, 9 Aug 2026 21:16:14 +0800 Subject: [PATCH] Add living-spec workflow for solo product documentation Introduce a lightweight current-product-truth skill, templates for product docs, change briefs and ADRs, and integrate documentation convergence into feature work. Co-authored-by: ChatGPT --- COVERAGE.md | 8 +- README.md | 12 +- UPSTREAM_MANIFEST.json | 1 + skills/living-spec/SKILL.md | 150 ++++++++++++++++++ skills/living-spec/references/adr-template.md | 35 ++++ .../references/change-brief-template.md | 41 +++++ .../references/product-doc-template.md | 35 ++++ skills/poteto-mode/playbooks/feature.md | 31 ++-- skills/pstack/SKILL.md | 4 +- skills/pstack/playbooks/feature.md | 31 ++-- 10 files changed, 324 insertions(+), 24 deletions(-) create mode 100644 skills/living-spec/SKILL.md create mode 100644 skills/living-spec/references/adr-template.md create mode 100644 skills/living-spec/references/change-brief-template.md create mode 100644 skills/living-spec/references/product-doc-template.md diff --git a/COVERAGE.md b/COVERAGE.md index 624e6ea..5e96bab 100644 --- a/COVERAGE.md +++ b/COVERAGE.md @@ -2,9 +2,9 @@ This pack aims for **full upstream pstack capability coverage**, ported to Agent Skills + adapters. -## Skills (45) +## Skills (46) -All upstream skills under `skills/` plus the portable hub `pstack`. +All upstream skills under `skills/` plus the portable additions `pstack` and `living-spec`. ## Playbooks (23) @@ -27,6 +27,10 @@ Mirrored in `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/`. | poteto-mode `scripts/` (orch, watch-pr) | omitted from pack copy (Cursor tooling); playbooks note fallbacks | | benny automations | kept under `references/automations/benny/skill-templates/` as `INSTRUCTIONS.md` (not discoverable by `npx skills add`) | +## Portable-only additions + +`living-spec` adds an optional current-product-truth workflow for solo projects. It is intentionally not part of upstream pstack and does not replace OpenSpec or another repository-native specification system. + ## External (never in upstream pstack either) `deslop`, `control-cli`, `control-ui` from `cursor-team-kit`. diff --git a/README.md b/README.md index 3e93c04..b05c3ef 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh insta | Area | Skills and assets | | --- | --- | | Entry | `pstack`, `poteto-mode` | -| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` | +| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `living-spec`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` | | Quality | `unslop`, `no-comments`, `technical-writing`, `bro` | | Principles | all 21 `principle-*` leaf skills | | Playbooks | 23 mirrored under `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/` | @@ -38,6 +38,16 @@ See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh insta The portable layer is an instruction protocol, not an emulator. It preserves workflow intent across hosts, but it cannot manufacture features a host does not expose. A runtime without subagents, model selection, browser control, or persistent modes will use the documented fallback and state the limitation. +## Living product documentation + +`living-spec` is an optional, solo-friendly documentation layer for projects that use pstack without a full specification framework. It keeps three concerns separate: + +- `docs/product/` describes the product's current, verified behavior; +- `docs/changes/` holds a temporary brief only for changes that span sessions, pull requests, or several modules; +- `docs/decisions/` records durable, non-obvious technical decisions with meaningful alternatives. + +The skill does not require documentation for internal refactors or trivial edits. It first inspects the repository for an existing canonical system such as OpenSpec, ADRs, or product docs, and reuses that system instead of creating a competing source of truth. Feature work converges documentation only after real-surface verification. + ## Session and mode behavior `/poteto-mode` is sticky when the active host supports persistent skill or mode state. On hosts without that lifecycle, treat it as active for the current conversation and invoke it again after a fresh session or a context reset. The engineering rules and playbooks remain portable even when the host cannot provide a native mode flag. diff --git a/UPSTREAM_MANIFEST.json b/UPSTREAM_MANIFEST.json index 15bc29a..231822c 100644 --- a/UPSTREAM_MANIFEST.json +++ b/UPSTREAM_MANIFEST.json @@ -13,6 +13,7 @@ "capability_contract_version": "1.0.0", "hand_maintained_skills": [ "pstack", + "living-spec", "poteto-mode", "how", "why", diff --git a/skills/living-spec/SKILL.md b/skills/living-spec/SKILL.md new file mode 100644 index 0000000..d903cfb --- /dev/null +++ b/skills/living-spec/SKILL.md @@ -0,0 +1,150 @@ +--- +name: living-spec +description: "Maintain a lightweight, current product-truth layer for pstack projects. Use for /living-spec inspect, draft, or converge; when a feature changes durable user-visible or business behavior; when work spans sessions or pull requests; or when current product docs, change briefs, or ADRs must stay aligned with verified implementation." +license: MIT +compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see pstack adapters. +--- + +# Living spec + +Keep the repository's current product behavior understandable without requiring a full specification framework for every task. + +This skill is intentionally small. It distinguishes: + +- **current truth** — what the product now promises; +- **change context** — what one in-progress change is trying to alter; +- **decision rationale** — why one durable technical choice won; +- **execution evidence** — how the work was performed and verified. + +Do not combine those into one ever-growing document. + +## Portability (required) + +1. Read the [pstack capability contract](../pstack/references/capability-contract.md), [workflow-quality defaults](../pstack/references/workflow-quality.md), and the active host adapter before delegation. +2. Use `explore` to discover existing documentation and behavior, `implement` for bounded documentation edits, `review` for independent convergence checks, `ask_user` only for product intent that evidence cannot settle, and `verify` for observable behavior. +3. Keep paths repository-relative. Do not depend on one vendor's session, transcript, or rules directory. +4. Small documentation decisions stay on the lead agent. Use helpers only when independent investigation or review will reduce a real blind spot. +5. Existing canonical systems win. If the repository already uses OpenSpec, another spec framework, established ADRs, or a product documentation hierarchy, update that system instead of creating a competing source of truth. + +## Default layout + +Use the repository's established layout when one exists. Otherwise prefer: + +```text +docs/ +├── product/ # current verified product behavior +├── changes/ # temporary briefs for larger in-progress changes +└── decisions/ # durable ADRs + +.audit/ # optional execution evidence from show-me-your-work +``` + +These paths are defaults, not requirements. + +## Persistence decision + +At the beginning of a feature, classify the change with these questions: + +1. Does it create or modify durable user-visible, operator-visible, API, security, billing, permission, data-retention, or business behavior? +2. Will it likely span multiple sessions, pull requests, repositories, owners, or independently shipped units? +3. Will a future maintainer need to know why a non-obvious choice was made? + +Choose the smallest persistence level that earns its cost: + +| Result | Action | +| --- | --- | +| No durable behavior change | No product document. Record `not required` with a reason. | +| Durable behavior, one bounded change | Update one current-truth product document during `converge`. | +| Durable behavior plus multi-session or multi-PR work | Create one temporary change brief, then converge into current truth. | +| Durable, non-obvious, hard-to-reverse decision with real alternatives | Add an ADR in addition to the relevant current-truth update. | + +Do not create an ADR for naming, local refactoring, routine library use, or an easily reversible implementation detail. + +## Operation: inspect + +Use before design or implementation. + +1. Read the user request, originating ticket/spec/acceptance list, and relevant repository instructions. +2. Discover existing product docs, specifications, ADR conventions, change briefs, and external authority documents. +3. Use `explore` to compare intended behavior with current code, tests, and the real runtime surface when available. +4. Classify any mismatch: + - **implementation bug** — documented or requested behavior is not delivered; + - **stale documentation** — verified behavior changed intentionally but current truth was not updated; + - **unresolved product decision** — evidence cannot determine what should happen; + - **implementation detail only** — no product-truth update is needed. +5. Return a documentation plan: + - persistence level; + - canonical files to read or update; + - whether a change brief is warranted; + - whether an ADR may be warranted; + - explicit `not required` reason when no persistence is needed. + +`inspect` is read-only unless the user explicitly asks to create the brief immediately. + +## Operation: draft + +Use only when `inspect` found that the change benefits from a persistent brief. + +1. Create one file using the [change brief template](references/change-brief-template.md). +2. Keep it concise: intent, scope, non-goals, acceptance, constraints, current design choice, verification plan, and product docs expected to change. +3. Prefer checkable behavior over implementation narration. +4. Link authoritative security, design-system, API, or operational docs rather than copying them. +5. Set status to `draft` or `in-progress`. The brief is not current product truth. +6. When implementation reveals a real design change, update the brief rather than allowing chat history to become the only record. + +Do not split a solo-project change into proposal/spec/design/tasks files unless the repository already follows that convention. + +## Operation: converge + +Use only after the implementation has been verified on the meaningful real surface. + +1. Re-read: + - the original intent and acceptance criteria; + - the final implementation diff; + - tests and runtime evidence; + - any change brief and decision trail; + - current product docs and ADRs. +2. Update current truth using the [product document template](references/product-doc-template.md), adapted to the repository's existing style. +3. Describe the final verified behavior: + - normal paths; + - failure and boundary scenarios; + - product constraints and non-goals that remain relevant; + - stable technical constraints only when maintainers must preserve them; + - repeatable verification surfaces. +4. Remove or rewrite stale current-behavior statements. Never append a new rule beside a contradictory old rule. +5. Do not rewrite desired intent to match a broken implementation. When verified behavior misses the accepted requirement, report a convergence gap and route back to implementation or an explicit product decision. +6. Create an ADR from the [ADR template](references/adr-template.md) only when the decision is durable, non-obvious, difficult to reverse, and had meaningful alternatives. +7. Resolve the temporary change brief: + - archive it when its decision history remains valuable; + - otherwise delete it after current truth converges; Git retains the history; + - never leave an `in-progress` brief after the change is complete. +8. Run a convergence review: + - for ordinary work, the lead compares docs, acceptance, diff, and verification; + - for high-risk or broad changes, use one read-only `review` helper with `model_role:critic`; + - classify the result as `pass`, `gap`, or `not applicable`. + +## Canonicality rules + +- One domain has one current-truth home. +- Current product docs describe **now**, not the chronology of implementation. +- Change briefs describe **this in-progress change**, not the whole product. +- ADRs describe **why a durable decision was made**, not product requirements. +- `.audit/` and `show-me-your-work` describe **execution evidence**, not current behavior. +- Git history preserves previous versions; do not retain obsolete rules in current docs merely for history. +- External authority documents stay authoritative. Link them and record only the change-specific constraint. + +## Output contract + +Always report: + +```text +Documentation: +- persistence: none | product-doc | change-brief | ADR +- current truth: +- change brief: +- decisions: +- convergence: pass | gap | not applicable +- evidence: +``` + +When there is a gap, name whether code, docs, or product intent must change next. diff --git a/skills/living-spec/references/adr-template.md b/skills/living-spec/references/adr-template.md new file mode 100644 index 0000000..28f6b4a --- /dev/null +++ b/skills/living-spec/references/adr-template.md @@ -0,0 +1,35 @@ +# ADR-: + +Status: proposed + +## Context + +What durable problem or constraint made a decision necessary. Explain why the choice is non-obvious to a future maintainer. + +## Decision + +State the selected option and the boundary it establishes. + +## Alternatives + +### + +Why it was viable and why it was rejected. + +### + +Why it was viable and why it was rejected. + +## Consequences + +- Benefits gained. +- Costs and constraints accepted. +- Migration, ownership, compatibility, or operational effects. + +## Verification + +Evidence that the selected decision works on the intended surface. + +## Revisit when + +Concrete conditions that would justify reopening the decision. diff --git a/skills/living-spec/references/change-brief-template.md b/skills/living-spec/references/change-brief-template.md new file mode 100644 index 0000000..e0c200a --- /dev/null +++ b/skills/living-spec/references/change-brief-template.md @@ -0,0 +1,41 @@ +# Change: + +Status: draft + +## Intent + +Why this change matters and which user, operator, or business outcome it improves. + +## Scope + +- Behavior included in this change. + +## Non-goals + +- Related behavior intentionally excluded. + +## Acceptance + +- [ ] One observable success or failure scenario per item. + +## Constraints + +- Product, security, compatibility, operational, dependency, or migration constraints that control the work. +- Link authoritative documents instead of duplicating them. + +## Design + +The current selected approach, key data shape, ownership boundaries, and important trade-off. Update this section when implementation evidence changes the design. + +## Decisions + +- Decision — reason — evidence. +- Keep only decisions another session would need. + +## Verification plan + +- Real surfaces and checks that will prove the accepted behavior. + +## Product docs to update + +- `docs/product/<domain>.md` or the repository's existing canonical equivalent. diff --git a/skills/living-spec/references/product-doc-template.md b/skills/living-spec/references/product-doc-template.md new file mode 100644 index 0000000..7484e86 --- /dev/null +++ b/skills/living-spec/references/product-doc-template.md @@ -0,0 +1,35 @@ +# <Domain> + +## Purpose + +One paragraph describing the user, operator, or business outcome this domain owns. + +## Current behavior + +- Describe behavior that is true in the verified product now. +- Use stable language that survives implementation refactors. +- Split unrelated behavior into separate bullets or subsections. + +## Failure and boundary scenarios + +- Describe important rejected, unavailable, expired, partial, or recovery paths. +- Include security, permission, billing, data-loss, and compatibility boundaries when relevant. + +## Product constraints + +- State durable in-scope and out-of-scope behavior. +- Do not list temporary implementation tasks. + +## Technical constraints + +Include only constraints future maintainers must preserve, such as an external protocol, storage ownership rule, migration invariant, or public compatibility contract. + +## Verification surfaces + +- Name repeatable UI, CLI, API, test, trace, or operational checks that prove the behavior. +- Prefer concrete paths or commands when stable. + +## Related decisions + +- Link relevant ADRs. +- Link external authoritative documents rather than copying them. diff --git a/skills/poteto-mode/playbooks/feature.md b/skills/poteto-mode/playbooks/feature.md index 3c62ece..56abfc3 100644 --- a/skills/poteto-mode/playbooks/feature.md +++ b/skills/poteto-mode/playbooks/feature.md @@ -1,21 +1,32 @@ ### Feature -**You own the design. Plan, review, verify.** Delegate implementation; stay in the lead. +**You own the design. Plan, review, verify, and converge durable product documentation.** Delegate implementation; stay in the lead. -1. `how` over the affected subsystem. -2. `architect` for parallel design exploration. Skipping stays as `architect skipped: <reason>`; do not fold the design decision silently into implementation. -3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped: +1. Run **living-spec inspect** for documentation persistence. + - If the change does not alter durable user-visible or business behavior, keep the todo as `living-spec: not required — <reason>`. + - If it does, identify the repository's canonical current-truth document, whether a temporary change brief is useful, and whether any design decision could qualify for an ADR. + - When the repository already uses OpenSpec or another canonical specification system, use that system instead of creating a parallel `docs/product/` tree. +2. `how` over the affected subsystem. +3. `architect` for parallel design exploration. Skipping stays as `architect skipped: <reason>`; do not fold the design decision silently into implementation. +4. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped: - **Blocking first steps.** Gates run before fan-out. - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. -6. Rebase into small, ordered commits; stack follow-ups. +5. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +6. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. +7. When Step 1 selected persistent documentation, run **living-spec converge** after real-surface verification. + - Update current product truth to the final verified behavior, not the initial plan. + - Remove or rewrite stale current-behavior statements instead of appending contradictory history. + - Archive or delete a temporary change brief according to repository convention; for a solo project, deletion after convergence is acceptable because Git preserves the history. + - Create an ADR only for a durable, non-obvious decision with meaningful alternatives. + - Review the implementation against any originating spec, ticket, acceptance list, and the updated current-truth document. A clean diff that misses the promised behavior is not complete. + - If Step 1 selected no persistence, keep `living-spec converge: n/a — <reason>` visible. +8. Rebase into small, ordered commits; stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. -7. If the design is contested, `interrogate` before shipping. -8. Run **Opening a PR**. +9. If the design is contested, `interrogate` before shipping. +10. Run **Opening a PR**. Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline; that owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries; spawn a fresh owner rather than chaining interrupts. -**Reply:** what you built, what you chose and why, open decisions. Tables for design alternatives. +**Reply:** what you built, what you chose and why, open decisions, and documentation status (`updated`, `not required`, or `gap`). Tables for design alternatives. diff --git a/skills/pstack/SKILL.md b/skills/pstack/SKILL.md index 36785fc..2bfbc67 100644 --- a/skills/pstack/SKILL.md +++ b/skills/pstack/SKILL.md @@ -25,7 +25,7 @@ Portable entry point for the pstack engineering system. It preserves the upstrea 1. Create a todo list. The first item reads the Principles index in `poteto-mode` or `references/principles-summary.md`, then opens every leaf principle that affects a real decision. 2. Match a playbook under `playbooks/` and copy its steps into the todo list before adding task-specific work. -3. Route to sibling skills as the playbook requires: `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `tdd`, `unslop`, and the verification skills. +3. Route to sibling skills as the playbook requires: `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `living-spec`, `tdd`, `unslop`, and the verification skills. 4. Use `verify` before declaring completion. A passing proxy is not proof when the reported problem appears on another surface. 5. State any degraded capability, such as unavailable helper spawning, model selection, transcript access, or runtime control. @@ -55,6 +55,8 @@ The entry pack includes: **Execution and adaptation:** `figure-it-out`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `tdd`, `typescript-best-practices`. +**Documentation and continuity:** `living-spec` maintains current product truth, temporary change briefs, and durable ADRs without forcing a full specification framework. + **Verification:** `create-verification-skill`, `maintain-verification-skill`. **Quality and prose:** `unslop`, `no-comments`, `technical-writing`, `bro`. diff --git a/skills/pstack/playbooks/feature.md b/skills/pstack/playbooks/feature.md index 3c62ece..56abfc3 100644 --- a/skills/pstack/playbooks/feature.md +++ b/skills/pstack/playbooks/feature.md @@ -1,21 +1,32 @@ ### Feature -**You own the design. Plan, review, verify.** Delegate implementation; stay in the lead. +**You own the design. Plan, review, verify, and converge durable product documentation.** Delegate implementation; stay in the lead. -1. `how` over the affected subsystem. -2. `architect` for parallel design exploration. Skipping stays as `architect skipped: <reason>`; do not fold the design decision silently into implementation. -3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped: +1. Run **living-spec inspect** for documentation persistence. + - If the change does not alter durable user-visible or business behavior, keep the todo as `living-spec: not required — <reason>`. + - If it does, identify the repository's canonical current-truth document, whether a temporary change brief is useful, and whether any design decision could qualify for an ADR. + - When the repository already uses OpenSpec or another canonical specification system, use that system instead of creating a parallel `docs/product/` tree. +2. `how` over the affected subsystem. +3. `architect` for parallel design exploration. Skipping stays as `architect skipped: <reason>`; do not fold the design decision silently into implementation. +4. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped: - **Blocking first steps.** Gates run before fan-out. - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. -6. Rebase into small, ordered commits; stack follow-ups. +5. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +6. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. +7. When Step 1 selected persistent documentation, run **living-spec converge** after real-surface verification. + - Update current product truth to the final verified behavior, not the initial plan. + - Remove or rewrite stale current-behavior statements instead of appending contradictory history. + - Archive or delete a temporary change brief according to repository convention; for a solo project, deletion after convergence is acceptable because Git preserves the history. + - Create an ADR only for a durable, non-obvious decision with meaningful alternatives. + - Review the implementation against any originating spec, ticket, acceptance list, and the updated current-truth document. A clean diff that misses the promised behavior is not complete. + - If Step 1 selected no persistence, keep `living-spec converge: n/a — <reason>` visible. +8. Rebase into small, ordered commits; stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. -7. If the design is contested, `interrogate` before shipping. -8. Run **Opening a PR**. +9. If the design is contested, `interrogate` before shipping. +10. Run **Opening a PR**. Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline; that owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries; spawn a fresh owner rather than chaining interrupts. -**Reply:** what you built, what you chose and why, open decisions. Tables for design alternatives. +**Reply:** what you built, what you chose and why, open decisions, and documentation status (`updated`, `not required`, or `gap`). Tables for design alternatives.