implementation-brief

Implementation Brief

Create the smallest durable artifact that another person or agent can execute without reopening material product or engineering decisions.

Core Boundary

• Use native planning for ordinary interactive planning that can stay in the current task.
• Use native execution, progress tracking, worktrees, and subagents after a plan is approved.
• Use this skill for the durable handoff artifact only.
• Do not create or edit a repository file unless the user asks for a saved artifact or names an output path.
• Do not execute the implementation while creating or auditing the brief unless the user separately authorizes execution.

Modes

Choose one mode from the request:

1. Create: Produce a new decision-complete implementation brief.
2. Audit: Classify an existing plan as ready, needs-decisions, or unsafe-to-execute, then identify or repair the gaps within the user's authorized scope.
3. Handoff: Adapt an approved plan for a named downstream person, agent, team, or automation interface.

Workflow

1. Establish The Artifact Contract

Identify:

• the audience or downstream executor
• whether the result stays in chat or is saved to a named path
• the definition of done
• any required schema or house template

Default to a compact implementation brief. Use a longer PRD only when durable coordination requires multiple dependent workstreams, cross-team ownership, a risky rollout, or an external executor.

2. Ground The Current State

Inspect the repository, source documents, interfaces, and existing behavior before drafting. Resolve discoverable facts from the environment instead of asking the user.

Record only evidence that changes the implementation approach. Avoid an inventory of every file inspected.

3. Close Material Decisions

Resolve approach, ownership, compatibility, migration, validation, and rollout choices before calling the artifact ready.

Ask the user only for preferences or authority that cannot be derived safely. Do not leave TBD decisions for the executor unless the user explicitly wants an exploratory brief.

4. Write The Smallest Sufficient Artifact

Read references/brief-template.md when creating or rewriting a durable artifact. Include only applicable sections.

Every ready brief must make these points clear:

• objective and measurable completion state
• relevant current-state evidence
• implementation decisions and boundaries
• interfaces, schemas, commands, or file locations that constrain the work
• verification and acceptance criteria
• rollout, rollback, or migration behavior when risk warrants it
• explicit assumptions that remain

Use dependency groups or workstreams only when sequencing matters. Do not force every action into a separate conversation or agent thread.

5. Audit For Execution Readiness

Before delivery, verify:

• an executor can start without choosing among material alternatives
• acceptance criteria prove behavior rather than activity
• commands and paths match the inspected environment
• risky mutations have a rollback or preservation strategy
• parallel work, if proposed, has disjoint ownership
• unresolved items are visible and genuinely non-blocking

Return needs-decisions instead of pretending an incomplete brief is executable. Return unsafe-to-execute when the plan could lose data, overwrite shared history, expose secrets, or mutate production without an adequate guardrail.

Native Execution Handoff

When useful, end with this compact block so the approved artifact can become a native long-running task:

Outcome: <observable end state>
Constraints: <boundaries and prohibited actions>
Verification: <tests or evidence that prove completion>

Do not add an execution ledger, completion log, or machine-readable manifest by default. Add one only when a named downstream system consumes it or the user explicitly requests it. Keep the human-readable brief authoritative when both forms exist.

Excluded Defaults

Do not add:

• vendor or model recommendations
• hard-coded context-size thresholds
• one-thread-per-conversation rules
• mandatory subagent delegation
• repeated completion logs inside the plan
• generic project-management ceremony
• implementation detail that the executor can discover cheaply without changing a decision

Durable decisions and verification belong in the artifact. Native agent mechanics do not.