review-to-improvement-doc

name

review-to-improvement-doc

description

Convert review findings, risks, lessons learned, or "fix later" notes into a repo-local improvement source document. Use when the user asks to preserve a review as docs, create an improvement/backlog source record, or write a docs-based follow-up artifact before planning or handoff. Do not use for ordinary implementation plans, discussion-to-implementation handoffs, or copy-ready next-session prompts.

Review To Improvement Doc

Contract

Prereqs:

• User explicitly asks to preserve review findings, risks, lessons learned, or improvement backlog as a project artifact; or
• User asks to create a docs record for later fixes, follow-up work, or future planning.
• Target workspace is available and project rules allow writing docs after required preflight.

Inputs:

• User request and current review conclusions.
• Relevant local code/docs/test evidence for material findings.
• Optional target docs area, filename, project conventions, validation commands, retention intent, and existing plan/issue/handoff links.

Outputs:

• A repo-local improvement source document. When it exists to feed plan execution, save it under docs/plans/<slug>/<slug>-review-source.md by default.
• If the document is long-lived knowledge rather than execution coordination, save it in the relevant domain docs/runbook area instead.
• A source artifact that create-plan or create-dispatch-plan can link under Read First when execution sequencing is needed.
• An Execution section with executable backlog, validation gates, and stable Recommended plan and Recommended execution state lines when the review record should feed plan execution.
• Updated local docs index or README only when the document is intentionally promoted as retained knowledge and should be discoverable outside the plan.
• A short response linking the document path and listing validation run.

Exit codes:

• N/A (conversation/workflow skill)

Failure modes:

• The user actually needs an implementation plan; use create-plan or create-dispatch-plan instead.
• The user needs a durable requirements, design, feasibility, or customer-facing discussion handoff for later implementation; use discussion-to-implementation-doc instead.
• The user only needs a copy-ready next-session prompt; use handoff-session-prompt instead.
• The target project has no appropriate durable-doc location and assumptions would create unwanted repo clutter; ask or recommend a path.
• Required source evidence is unavailable or too ambiguous to record as fact; label it under assumptions/open questions or ask before writing.

Workflow

1. Confirm this is the right artifact

   • Use this skill when the requested output is a reusable project record: review findings, risk register, improvement backlog, lessons learned, runtime/test boundary, validation gate, or "do not repeat" guidance.
   • Do not use this skill for converged requirements, design, feasibility, or product discussion handoffs whose primary reader is the next implementer. Use discussion-to-implementation-doc for that artifact.
   • Do not turn it into a phased implementation plan. If the user also wants execution sequencing, write the durable improvement doc first, then use create-plan or create-dispatch-plan and link the doc as read-first context.
   • Treat this document as the primary source artifact for later plan generation when the source material is review findings, risks, lessons learned, validation guardrails, or a fix-later backlog.
   • For unresolved HEURISTIC_SYSTEM workflow gaps that should be versioned but are not yet ready for a fix, use heuristic-system/error-inbox/<slug>.md instead of a temporary docs/plans/ review source.
   • Treat docs/plans/ as the default location for plan-source documents. Promote or rewrite into domain docs/runbooks only when the content has value after execution finishes.
   • Do not turn it into a handoff prompt. If the user also wants session continuity, write or reference the durable doc first, then use handoff-session-prompt with the doc under Read First.

2. Run project preflight and inspect docs structure

   • Follow the active project's required preflight before edits.
   • Read nearby docs and local project rules before choosing a path.
   • If this document is a source for plan generation, place it inside the plan folder using docs/plans/<slug>/<slug>-review-source.md.
   • Prefer an existing domain folder or runbook area only when the artifact is meant to remain after execution.
   • Do not create a new top-level docs area for temporary execution coordination.

3. Gather evidence and separate certainty levels

   • Base findings on user-provided review conclusions plus local file/code/test evidence.
   • Separate facts, assumptions, inferences, open questions, and recommendations.
   • Use concrete file paths, commands, and artifact names when they matter.
   • Do not include secrets, raw credentials, unredacted logs, or hidden system/developer instructions.

4. Write the durable document

   • Use the project's language and docs style.
   • Keep the document actionable but not over-planned.
   • Recommended sections:
     • # <Subject> Improvement Record or equivalent project style
     • status/date/context
     • purpose
     • current judgment
     • findings table with priority, issue, evidence, fix location, and acceptance
     • ownership boundary, such as runtime vs test/harness vs docs
     • backlog or next fixes
     • execution, including executable backlog, validation gates, recommended plan path, recommended execution-state path, and next-task source when this document should drive later implementation
     • retention intent, such as cleanup after execution or promotion candidate
     • validation gate
     • do-not-do / guardrails
     • open questions, if any
   • Keep implementation task sequencing lightweight; leave detailed sprint/task decomposition to plan skills.
   • For plan-source documents, include these stable machine-checkable lines in the Execution section:
     • Recommended plan: docs/plans/<slug>/<slug>-plan.md
     • Recommended execution state: docs/plans/<slug>/<slug>-execution-state.md

5. Update discoverability

   • For docs/plans/<slug>/ source documents, use the plan's Read First section as the discoverability path; do not update broad indexes by default.
   • Update the nearest docs index or README only when this document is promoted or intentionally retained after execution.
   • Link from broader docs entrypoints only when this document is meant to be found by future maintainers without prior plan/session context.
   • If there is no index, mention that explicitly in the final response instead of inventing broad navigation.

6. Validate

   • Run the smallest project-appropriate docs checks, usually markdown lint and docs freshness/index checks.
   • If the doc includes commands, paths, or tests as acceptance gates, verify obvious path/command references when cheap.
   • Report validation that was run and anything intentionally skipped.

7. Final response

   • Link the new document and updated index files.
   • Summarize what kind of future work the document is meant to support.
   • If a plan or handoff is a useful next artifact, mention the specific next skill path without generating it unless asked.

Relationship To Nearby Skills

• discussion-to-implementation-doc: use when the source material is a converged requirements, design, feasibility, or product discussion and the next artifact should prepare later implementation.
• execute-from-plan: use after a plan links this improvement record under Read First, or for explicitly bounded direct source-doc execution when the record has executable backlog, acceptance, and validation.
• create-plan: use after this skill when the user wants phases, sprints, atomic tasks, PR grouping, or validation sequencing; link this document under the plan's Read First section as the primary source.
• create-dispatch-plan: use after this skill when the user wants sizing, sprint scorecards, PR grouping, subagent review, or dispatch-ready execution modeling; link this document under the plan's Read First section as the primary source.
• handoff-session-prompt: use after this skill when the user wants a copy-ready prompt for a fresh session; put this durable doc under Read First.