# Briefs Work

> Use at start of any work session. Reads where you left off in CURRENT.md and executes the planned task — without relitigating decisions or declaring the task done.

- Skill: `naxoc/briefs-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add naxoc/briefs-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/naxoc/briefs-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: naxoc (https://skillmd.com/u/naxoc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/naxoc/briefs-work

---


# Briefs: Work Session

Executor mode. CURRENT.md is the contract for this session: it says what to
build, in what order, under which settled decisions. Your job is to work
through it — not to redesign it.

## Starting a Session

**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

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:** Read CURRENT.md. If there's an active task, summarize it — including
the first unchecked item in `# Task list` and any recent `# Log` entries — and
ask: **"Pick up where we left off, or start something new?"**

If CURRENT.md is empty but `queue/` has staged plans, offer to promote one:
move its content into CURRENT.md, delete the queue file, add the task to
BACKLOG.md's `# Backlog` if missing — then **re-verify before executing**:

- Check the plan's named files, functions, and patterns still exist as
  described (the Approach header says which commit it was planned against —
  `git diff --stat <that-sha>..HEAD` shows what moved underneath it).
- **Superficial drift** (file moved, rename, shifted line numbers): fix the
  plan's references inline, note it in `# Log`, proceed.
- **Structural drift** (a pattern to mirror was refactored away, a settled
  decision conflicts with current reality): stop and tell the user the plan
  needs a `/briefs-plan` pass — do not improvise around a broken plan.

**Step 3:** Check the shape of the task:
- **Approach is filled in** → execute it (see below).
- **No Approach and the task is non-trivial** (multiple files, design choices,
  unknowns) → recommend running `/briefs-plan` first, ideally on a stronger
  model. Planning done here, ad hoc, is how tasks go sideways.
- **No Approach but the task is small and obvious** (typo-level, single-file,
  no decisions) → just do it; a plan would cost more than the work.

## Executing

- Work the `# Task list` in order. Follow the `## Order of work` gates — if a
  step says "make test green", it means green before moving on.
- **Settled decisions are settled.** If `# Approach` says the status code is
  hardcoded, do not add a config option because it "seems better". If you
  believe a decision is actually wrong or impossible, stop and say so — with
  the evidence — instead of silently deviating.
- **When reality disagrees with the plan** (a named file doesn't exist, a
  pattern changed, an API behaves differently): make the smallest sensible
  adaptation and record it in `# Log` (see below). If the deviation would
  change something under `## Decisions (settled)`, stop and ask instead.
- Respect `## Hard rules for the implementing session` absolutely.
- If the user asks for something outside the active task, add it to BACKLOG.md
  (under `# Backlog`) rather than expanding the session's scope — unless the
  user explicitly says to switch.

## File rules — what this skill may and may not write

These rules exist because sessions used to declare work "done" before the user
ever reviewed or tested it. The boundary: **you record progress; only the
user, via `/briefs-done`, records completion.**

- **CURRENT.md** — keep it live during the session:
  - Tick `# Task list` checkboxes when an item is *implemented and verified*
    (tests/checks pass). A ticked box means "built and checked", **not**
    "accepted" — acceptance happens in `/briefs-done` after the user reviews.
  - Append dated one-liners to `# Log`: deviations from the Approach (with
    why), blockers hit, anything the next session must know to continue cold.
    When the user hands you a commit SHA for finished subtask work, record it
    here too ("backend committed as abc1234") and mention that
    `/briefs-done` can checkpoint it into PROGRESS.md without closing the task.
  - Add reviewer-relevant facts to `# Review notes` as you create them
    (surprising changes, migration notes, things to test manually).
  - **Never** reset CURRENT.md, remove the task, or write anything that
    declares the task finished. Even with every box ticked, the task is
    "awaiting review" — say exactly that, and point the user at `/briefs-done`.
- **BACKLOG.md** — may append newly discovered work to `# Backlog`. Nothing else.
- **PROGRESS.md** — never touch. Only `/briefs-done` writes there.
- **NOTES.md** — may append reusable learnings (gotchas, commands, references).

## Ending a session

Before stopping — whether finished or interrupted — make CURRENT.md reflect
reality: boxes ticked to match verified work, `# Log` updated with current
state and the concrete next step. A fresh session must be able to continue
from the file alone.

If all boxes are ticked: report what was built and how it was verified, then
hand off — "ready for your review; run `/briefs-done` when you've reviewed and
committed." Do not celebrate completion; that's the user's call.

## Rules

- One task at a time. CURRENT.md holds exactly one active task. If you're
  tempted to add a second, put it in BACKLOG.md instead. CURRENT.md must stay
  short (max 3 items) — if it has more, mention it and suggest `/briefs-health`.
- Keep output concise. Report outcomes and load-bearing findings, not narration.
- Don't use numbered lists in the briefs files unless order truly matters —
  they make reordering painful.