radin-plan

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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

```bash
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.

  ```bash
  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
     `/mattpocock-skills:research` naming
     `<repo root>/.claude/.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:

     ```bash
     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 `/mattpocock-skills: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.

   ```bash
   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>

```markdown
# 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>.

From shortcuts/radin, MIT.

More from shortcuts/radin