/radin-plan

name: radin-plan
description: |
  Use for /radin-plan, "plan this backlog entry", "write a plan for X before
  we execute it". Writes an implementation plan for one backlog entry,
  touching no code. Scope is one task, not the whole backlog.
<!-- host:claude -->
argument-hint: "<task id | title | keyword>"
<!-- /host -->

Plan a Backlog Entry

**You own the plan, not the code.** The plan is a checklist an executor runs box by box, and a reviewer audits from the evidence each box names. It runs inline in whichever context invokes it. A caller that cannot reach the user says so in its prompt; the branches marked "non-interactive" are then the defaults, and anything only the user could settle is reported and stops the run.

Step 1: Resolve the task scope

RADIN_CLI backlog plan-target "<scope id/title/keyword>"

It prints `id`/`title`/`task_file`/`plan_file` lines, plus a `facts<TAB><path>` line when the entry carries one, plus one `plan<TAB><path>` line per plan the entry already has. Route on its exit code:

• **0**: resolved and unplanned. Use it.
• **1**: nothing matches. The task isn't in the backlog yet. Classify it into

`feat` (new capability), `fix` (broken behavior), `chore` (maintenance: docs, tooling, cleanup) or `refactor` (structure only, no behavior change), create it without asking, then re-run `plan-target` on the printed id.

  RADIN_CLI backlog add <category> "<short title>" <<'EOF'
  <the task as the caller stated or clearly implied it, and why it matters
  if not already obvious>
  EOF

• **2**: several entries match; it prints them as `candidate` lines on stderr.

Ask which one.

• **3**: already planned; the `plan` lines are the existing paths. Show them and

ask whether to re-plan (overwrite) or stop. Stop unless confirmed.

Non-interactive, for exits 1-3: report what `plan-target` printed and stop. The scope came from an existing entry, so no match means backlog drift: the run adds no entry, picks no candidate, and overwrites no plan.

Step 2: Judge whether the scope should split

Split only when the entry bundles unrelated changes that can each be planned on its own. Interactive: state your read (split or not, and why) and confirm it; a confirmed split lists short titles and one-line descriptions with full coverage and no overlap. Non-interactive: no split.

Step 3: Write each plan

For each sub-task, in order:

1. Read the entry's file. A sub-task from a split has only its one-line Step 2 description as scope, so plan just that part. 2. Explore the repo as far as the plan needs, by `RADIN_LIB/radin-explore-rule.md`. Carry the project's own vocabulary into the plan, its glossary or domain-model doc where it has one, and respect any ADR covering the area. 3. Settle each open fact before you write:

• A fact you can observe by running something (a command, a scratch

script, a one-off probe outside the repo tree) is yours to run. Delete the scratch file after.

• Third-party API or library behavior local code cannot confirm: read the

entry's `**Fact:**` lines and the `facts` file Step 1 printed first. Still open, interactive: hand the question to `@@skill:research@@` naming `<repo root>/.radin/state/facts/<task-id>.md` as the file to write to, plan the parts that do not hinge on it meanwhile, then record it:

     RADIN_CLI backlog fact "<id>" measured "<the answer in one sentence, naming the source that owns it>" --long "<the state/facts path above>"

If the skill asks you anything, drop it and name the question in the report. Non-interactive: name the question and stop, because `radin-batch`'s router owns the research arm (`lib/radin-batch-clarify.md`) and appends the answer to this task. 4. Sketch the seam the change will be tested at: the highest existing one, and a new one only at the highest point available. Interactive: confirm it with the user. Non-interactive: write on. 5. Apply the ponytail ladder already in your context to produce the plan. When the plan places a new module boundary or reshapes an interface, invoke `@@skill:codebase-design@@` for that part. Write it to the template below. Non-interactive: a question the entry, the repo and this conversation cannot answer ends the run as a report line, not an open decision in the plan. 6. Save the plan at the `plan_file` path Step 1 printed. For a sub-task from a split, re-run `plan-target "<id>" "<sub-task short title>"` and use the `plan_file` it prints. 7. Insert the pointer. `add-plan` runs `plan-lint` first. On a non-zero exit it records nothing and prints one line per defect: fix each, then run it again.

   RADIN_CLI backlog add-plan "<id>" "<the plan_file path>"

This skill's whole output is the plan file(s), the plan pointer, and, when research ran, the `**Fact:**` line and `facts` pointer. No source file is edited, no build or test runs, nothing is committed.

The plan template

Keep every heading, in this order. A section that does not apply reads `n/a: <reason>`, so a reader sees it was considered.

<plan-template>

# Plan: <task title>

**Task:** `<task id>` — <the `task_file` path Step 1 printed>

## Outcome

<One or two lines: what is true of the codebase once this plan is implemented.>

## Decisions

<Every choice the executor would otherwise have to make, settled here:>

1. <The question> → <the settled answer>. Why: <one line>. Source: <`path:line`, the read-only command that produced it, or the owning doc for third-party behavior>.

<A change that adds state settles its data shape here, before any logic: a
state machine over scattered booleans, a table over branching, a typed model
over repeated shape assumptions. A claim with no source is an open question,
which ends the run per Step 3; a decision the executor has to invent is a
defect in this plan.>

## Alternatives rejected

- <Each a