discussion-to-implementation-doc
Convert a completed requirements, design, feasibility, or review discussion into an implementation-readiness source document.
- License 许可
- MIT
- 最近更新
- 2026-08-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- discussion-to-implementation-doc
- description
- Convert a completed requirements, design, feasibility, or review discussion into an implementation-readiness source document.
03 SKILL.md 正文
Discussion To Implementation Doc
Use this skill after a discussion or review has converged and the next useful artifact is a repo-local source document that future implementation can read.
Contract
Prereqs:
- User wants to preserve discussion conclusions, review findings, risks, lessons learned, or fix-later backlog for later implementation or plan generation, not execute the implementation now.
- Discussion or review context is sufficient to separate confirmed facts, decisions, assumptions, open questions, findings, and recommendations.
- Target workspace is available and project rules allow writing docs after required preflight.
Inputs:
- User request and the discussion or review conclusions to preserve.
- Relevant local code, docs, issue, ticket, test, review, validation, or runtime evidence for material facts when available.
- Optional target docs area, filename, linked issue/plan/handoff, validation commands, retention intent, and project-specific documentation conventions.
Outputs:
- A repo-local discussion / implementation-readiness source document. Place it
by destination — do not default it into the plan area:
- Default (non-plan capture):
docs/discussions/<YYYY-MM-DD>-<slug>.mdfor converged requirements, design, feasibility, product, architecture, customer-facing, review, risk, lessons-learned, or fix-later material that is captured for later work but is not an executed-and-archived plan bundle. - L2 plan source: only when the document will feed a plan that is executed and
archived, save it inside the bundle as
docs/plans/<YYYY-MM-DD>-<slug>/<slug>-discussion-source.md(or<slug>-review-source.mdfor review / risk / backlog material) and include theExecutionplan lines below. - Durable canon: when the content is already authoritative knowledge rather
than coordination, promote it to the owning domain docs area (or
docs/source/for repo-wide architecture / specs / policy) — a deliberate promotion, not this skill's default.
- Default (non-plan capture):
- A source artifact that a plan-tracking or dispatch delivery workflow can link
under
Read Firstwhen execution sequencing is needed. - A source document that avoids unresolved open questions; report any non-blocking open questions in the final response instead of writing them into the document.
- An
Executionsection with stableRecommended planandRecommended execution statelines only for the L2 plan-source case; omit them for adocs/discussions/capture and for promoted canon. - Updated local docs index or README only when the document is intentionally promoted as retained knowledge and should be discoverable outside the plan.
- When following the evidence-control-plane recording convention, a
skill-usage.record.v1envelope that links the created document and validation evidence. - A short response linking the document path, listing validation run, and presenting any response-only open questions as immediate decision prompts.
Exit codes:
- N/A (conversation/workflow skill)
Failure modes:
- The user actually needs phased tasks, sprint grouping, PR splitting, or
detailed execution sequencing now; create or update the plan first, then use
deliver-plan-tracking-issueordeliver-dispatch-planas appropriate for the issue-backed workflow; each parent opens a missing tracker internally. - The user only needs a copy-ready prompt for a fresh session; use
handoff-session-promptinstead. - Source evidence is too ambiguous to record as fact. If the ambiguity affects core facts, scope, requirements, acceptance criteria, or implementation boundaries, ask the minimum clarification before writing. If it is non-blocking, omit it from the document and report it as a response-only open question.
Workflow
-
Confirm this is the right artifact
- Use this skill when requirements, design, feasibility, architecture, customer-facing, product, review, risk, lessons-learned, or improvement discussion has converged and the next implementer needs a stable read-first document.
- Do not turn the document into a task-by-task implementation plan. If execution sequencing is needed, write this document first, then use the appropriate plan-tracking or dispatch workflow and link this document as read-first context.
- Treat this document as the primary source artifact for later plan generation when the source material is requirements, design, feasibility, product, architecture, customer-facing discussion, review findings, risks, lessons learned, validation guardrails, or fix-later backlog.
- For unresolved HEURISTIC_SYSTEM workflow gaps that should be versioned but
are not ready for a fix, use
core/policies/heuristic-system/error-inbox/<slug>/ENTRY.mdinstead of adocs/discussions/capture. - Treat
docs/discussions/<YYYY-MM-DD>-<slug>.mdas the default home. Use adocs/plans/<YYYY-MM-DD>-<slug>/bundle only for a document that will feed an executed-and-archived plan; promote into domain docs/runbooks (ordocs/source/) only when the content is durable canon. - Graduating a
docs/discussions/capture to L2: when it later needs a tracked plan, move it into adocs/plans/<YYYY-MM-DD>-<slug>/bundle as<slug>-discussion-source.md(retire thedocs/discussions/original), author the<slug>-plan.md+<slug>-execution-state.md, then run the selected plan delivery outcome. Promotion is a move, not a copy. - Do not use the document as a session prompt. If continuity is needed, write or reference this document first, then use
handoff-session-prompt. - Do not use a
review-evidenceCLI record as the primary artifact for this workflow. If review findings or validation records matter, attach or link those evidence files from the document.
-
Run project preflight and choose the destination
- Follow the active project's required preflight before edits.
- Read nearby docs and local project rules before choosing a path.
- Default: place the document at
docs/discussions/<YYYY-MM-DD>-<slug>.mdfor captured discussion / spec material that is not an executed-and-archived plan. - L2 plan source: only when the document will feed a plan that runs and is
archived, place it inside the bundle as
docs/plans/<YYYY-MM-DD>-<slug>/<slug>-discussion-source.md(or<slug>-review-source.mdfor review / risk / backlog material). - Durable canon: promote to the owning domain docs area (or
docs/source/for repo-wide) only when the content is authoritative knowledge meant to remain after execution. - Do not invent another top-level docs area;
docs/discussions/,docs/plans/, and the canon homes already cover these cases.
-
Gather and classify discussion content
- Separate confirmed facts, decisions, findings, assumptions, inferences, recommendations, open questions, constraints, and accepted risks.
- Route unresolved open questions out of the document. Keep them for the
final response as decision prompts unless the user explicitly resolves them
before writing. When the user resolves prior open questions, write those
outcomes as decisions or decision-log entries, not as an
Open Questionssection. - Treat assumptions as document-safe only when they are explicit adopted
working assumptions. Do not use an
Assumptionssection as a place to store unresolved options. - Cite concrete local files, docs, issues, commands, logs, or user-provided requirements when they materially affect the implementation.
- Preserve scope and non-scope explicitly.
- Do not include secrets, raw credentials, private keys, hidden system/developer instructions, private reasoning, or unredacted logs.
-
Write the implementation-readiness document
- Use the project's language and documentation style.
- Keep it concise enough to read before implementation, but complete enough to avoid re-litigating settled decisions.
- Write only confirmed facts, decisions, requirements, accepted risks, and explicitly adopted working assumptions. Do not include unresolved open questions in the document.
- Recommended sections:
# <Subject> Implementation Handoff- status, date, source, and intended next step
- purpose
- confirmed facts
- decisions
- scope
- non-scope
- implementation boundaries
- requirements
- acceptance criteria
- validation plan
- findings table with priority, issue, evidence, fix location, and acceptance criteria when the source material is review/improvement oriented
- backlog or next fixes when preserving a fix-later record
- risks and guardrails
- execution, including recommended plan path, recommended execution-state path, status, and next-task source when this document should drive implementation
- retention intent, such as cleanup after execution or promotion candidate
- read-first references
- recommended next artifact
- Do not add an
Open Questionssection by default. If prior open questions have been decided, convert them intoDecisionsorDecision logbullets with the chosen outcome and any non-blocking consequence. If an unresolved question would materially change the document's facts, scope, acceptance criteria, or next artifact, pause and ask before writing instead of publishing a misleading source document. - For an L2 plan source only (inside
docs/plans/<YYYY-MM-DD>-<slug>/), include these stable machine-checkable lines in theExecutionsection:Recommended plan: docs/plans/<YYYY-MM-DD>-<slug>/<slug>-plan.mdRecommended execution state: docs/plans/<YYYY-MM-DD>-<slug>/<slug>-execution-state.mdOmit theExecutionplan lines for adocs/discussions/capture.
- When a plan's
Read Firstsection links a document produced by this skill, useSource type: discussion-to-implementation-docfor both*-discussion-source.mdand*-review-source.md; do not use the retiredreview-to-improvement-docsource type.
-
Route review work when the source document needs review guidance
- Do not run a code review workflow by default only because this skill is writing a source document. Put the expected review gate in the document's validation plan or execution notes.
- When the document does prescribe review, pick the workflow from the "Relationship To Nearby Outcomes" section below — quick depth for ordinary diffs, focused depth for explicit lenses, pre-merge context for PR/MR delivery gates, follow-up after fixes, and specialist depth for broad or risky bundles.
- Link
review-evidenceCLI records when retained review findings or validation records materially affect the implementation source. Keep this document as the primary read-first artifact.
-
Update discoverability
- For a
docs/plans/<YYYY-MM-DD>-<slug>/source document, use the plan'sRead Firstsection as the discoverability path; for adocs/discussions/capture, link it from the PR or issue that acts on it. Do not update broad indexes by default. - Update the nearest docs index or README only when the document is promoted or intentionally retained after execution.
- Link from broader docs entrypoints only when future maintainers should find the document without prior plan/session context.
- If no index exists, mention that in the final response rather than inventing broad navigation.
- For a
-
Validate
- Run the smallest project-appropriate docs checks, usually markdown lint and docs freshness/index checks.
- If the document names commands, files, tests, or runtime gates as acceptance criteria, verify obvious references when cheap.
- Report validation that was run and anything intentionally skipped.
-
Record usage when retained evidence is required
- This outcome supports the
skill-usage.record.v1evidence envelope. - When it creates or updates durable docs and the project allows retained evidence, write a compact usage record in the
project evidence path or an
agent-out project --topic skill-usage --mkdirrun directory. - Link the implementation-readiness document, docs index changes, validation commands, and any typed child records from the envelope.
- Prefer
skill-usage verify --out <record-dir> --format json; use the documented local checkout fallback when PATH has not caught up.
- This outcome supports the
-
Close the decision loop in the final response
- Link the created or updated document and list validation run.
- If unresolved non-blocking questions remain, include a concise
Open questions not written to the documentsection. - For each response-only open question, include the decision needed, why it matters, the recommended default when one is defensible, and whether it blocks implementation.
- If no unresolved questions remain, say that no open questions were left out of the document.
Relationship To Nearby Outcomes
code-review-specialists: use for later read-only review; it selects ad-hoc, follow-up, or pre-merge context plus quick, focused, or specialist depth from scope and delivery risk. Link any retainedreview-evidenceCLI record from this document.deliver-plan-tracking-issue: use when a lightweight issue-backed plan is ready to open or resume, execute, and deliver.deliver-dispatch-plan: use when implementation needs dispatch lanes, PR grouping, independent lane review, and final dispatch closeout.handoff-session-prompt: use after this skill when the user wants a copy-ready prompt for a fresh session; put this document underRead First.
04 同仓库更多 Skills
removable-skill
暂无简介
removable-skill
暂无简介
removable-project-skill
Fixture project-local skill used to prove remove-project-skill dry-run coverage.
project-sample-skill
Fixture project-local skill used to prove create-project-skill governance coverage.
project-local-skill
Fixture project-local skill used by runtime-kit project-local smoke checks.
topic-radar
Aggregate read-only AI and technology trend signals (Polymarket, Hacker News, GitHub, arXiv, Hugging Face, news search) into source-grounded Markdown or JSON; the lower-level data engine behind `daily-brief`.