Briefs plan

Briefs: Plan a Task

You are the architect, not the crew. The output of this session is not code — it is a CURRENT.md so unambiguous that a cheaper model (or a future session with zero memory of this conversation) can execute it without making a single significant decision. Every decision you fail to settle here gets made later, worse, by whoever executes.

Best run on the strongest model available; execution can then happen on a cheaper one.

Step 1: Find the briefs folder

Check these in order:

• Read .claude/briefs-path for a saved path
• Check if .briefs/ exists in the project root
• If neither works, ask the user for the path

Read CURRENT.md and BACKLOG.md. If the folder has a PLAN.md but no BACKLOG.md, it predates the rename — treat PLAN.md as BACKLOG.md and offer to mv it.

Step 2: Pick the task

• If the user named a task, use it.
• If CURRENT.md already has an active task with an empty/thin # Approach, offer to plan that.
• Otherwise propose the top of BACKLOG.md's ## Up next.

If CURRENT.md holds a different in-flight task, offer to plan ahead: the plan is written to queue/<task-slug>.md in the briefs folder (same format as CURRENT.md; mkdir -p the queue dir) instead of CURRENT.md, and gets promoted when the active task closes out. This is how the user plans the next task with a strong model while a cheaper one executes the current task in another session. In queue mode, don't touch BACKLOG.md — the executing session may be writing it; promotion handles the bookkeeping later.

Step 3: Investigate — cheaply

Ground the plan in facts before making any decision. Read the actual code, the actual scripts, the actual mockups — never plan from assumption when the source is on disk.

Delegate the bulk reading. If subagents are available, send an Explore-type subagent (on a cheaper model if the harness allows) to map the relevant code: existing patterns to mirror, file paths, conventions, tests to copy. Keep this session's context for decisions, not file dumps. Read directly only what is load-bearing: the mockup, the one function being wrapped, the API being called.

Step 4: Interview the user

Only ask about genuinely open decisions — things investigation could not settle and that change what gets built. For each, give your recommendation with a one-line reason. Batch related questions (3–5 max); don't drip-feed.

Do NOT ask about things the codebase already answers (conventions, patterns, naming) or things that don't change the outcome. The user is here to decide, not to be quizzed.

Step 5: Write the Approach into CURRENT.md

Fill CURRENT.md using this structure (create the missing sections, keep the user's # Context in their own words):

Working on: **<task title>**
Branch: `<branch>`

# Context
<the user's framing: why this task exists, constraints, links, opinions>

# Approach
*Planned <date> with <model> against commit <short-sha>; execution may run on
a cheaper model. Decisions below are settled with the user — do not relitigate
them.*

## Decisions (settled)
- <each decision from the interview, stated as a rule, with the chosen option>

## <one section per layer/area, e.g. "Backend — internal/api">
<what to build, with exact file paths, functions, and existing code to mirror
— "follow the pattern in `internal/api/site_delete.go`" beats three
paragraphs of description>

## Order of work
1. <steps with a verification gate each, e.g. "make test green">

## Hard rules for the implementing session
- <project rules that must survive the handoff: never commit/push, never run
  the app, security boundaries, etc. Pull these from CLAUDE.md/AGENTS.md —
  restate them; don't assume the executor reads everything>

# Task list
- [ ] <3–8 checkboxes matching the order of work>

# Log
<empty — the executing session appends dated notes here>

# Review notes
<empty — filled during execution/review with what a reviewer needs to know>

Quality bar for the Approach:

• Exact paths and line references, verified during investigation — not "add an endpoint somewhere".
• Named siblings to mirror for every new file/test.
• Settled decisions stated as rules, so the executor cannot mistake them for suggestions.
• If part of the plan says "check X first", you haven't finished planning — go check X now.
• The commit stamp (git rev-parse --short HEAD) is what makes plan rot detectable later — queued plans especially can go stale while another task rewrites the code they reference.

Step 6: Update BACKLOG.md and hand off

• Ensure the task appears in BACKLOG.md ## Up next (add it if the user brought it fresh).
• Tell the user: review the Approach, then start execution with /briefs-work — in a fresh session, on a cheaper model if they want. For larger plans, suggest natural checkpoint splits (e.g. backend session → user reviews + commits → frontend session).

Queue mode instead: skip BACKLOG.md; tell the user the plan is staged at queue/<slug>.md and will be offered for promotion when /briefs-done closes the active task (or by /briefs-work when CURRENT.md is free). The promoting session re-verifies the plan against the code as it stands then.

File rules for this skill

• CURRENT.md: full write access — that's the deliverable. In queue mode: don't touch it; write queue/<slug>.md instead.
• BACKLOG.md: may add/move the planned task within ## Up next / ## Backlog. In queue mode: don't touch it.
• PROGRESS.md: never touch. Only /briefs-done writes there.
• NOTES.md: may append genuinely reusable learnings discovered while investigating.