# Briefs Plan

> Plan a task with the user before any code is written: investigate cheaply, settle the open decisions together, and write a complete Approach into CURRENT.md that a cheaper model can execute without judgment calls.

- Skill: `naxoc/briefs-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add naxoc/briefs-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/naxoc/briefs-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: naxoc (https://skillmd.com/u/naxoc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/naxoc/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 item of BACKLOG.md's `# Backlog` — it is roughly
  ordered, so the top few are what matters 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, **add one line to the backlog item the plan came
from** — `*Planned 2026-08-05 → `queue/<slug>.md`*` — so the item says a plan
exists and where. Without it the queued plan is invisible from the list it came
out of. Otherwise **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):

```markdown
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's `# Backlog` (add it if the user
  brought it fresh). Write new items as `## Title` followed by a `*tag*` line;
  if the file still uses `- [ ]` checkbox items, match whatever is already there
  rather than mixing two styles in one file.
- 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 `# Backlog` /
  `# Backlog`. In queue mode: add only the one-line pointer to the source item.
- **PROGRESS.md**: never touch. Only `/briefs-done` writes there.
- **NOTES.md**: may append genuinely reusable learnings discovered while investigating.