---
name: radin-plan
description: |
  Write a step-by-step implementation plan for one backlog entry, without
  touching code. Scope is one task (a title/keyword), not the whole backlog.
  Use for /radin-plan, "plan this backlog entry", "write a plan for X before
  we execute it". radin-execute delegates here for any entry too complex to
  implement directly.
---
# Plan a Backlog Entry

Turn one backlog entry into one or more implementation plans, without
writing any code. It runs inline in whichever context invokes it. When the
invoking context cannot reach the user (e.g. radin-execute's planning
sub-agent), the caller says so, and every question below then takes the
non-destructive branch marked "non-interactive". A sub-agent can neither
reach the user nor call `AskUserQuestion`, so `/mattpocock-skills:grilling`
is interactive-only here: there is no way for it to get an answer. Same for
`/mattpocock-skills:research`, which spawns its own agent whose result may
never come back within the turn. Each "non-interactive" branch below says
what to do instead.

## Step 1: Resolve project namespace

All backlog reads/writes go through the shared CLI at
the `RADIN_CLI backlog` CLI. Never hand-edit the backlog's
index or task files, and never compute their paths yourself. Get the paths
(this also creates the state/plans/reviews/tasks directories):

```bash
RADIN_CLI backlog env
```

Read `REPO_ROOT`, `NAMESPACE_DIR`, `BACKLOG_INDEX`, `BACKLOG_TASKS_DIR` from
its output. Re-run this line in any later Bash call that uses them.

## Step 2: Resolve the task scope

```bash
RADIN_CLI backlog find "<scope id/title/keyword>"
```

It prints one `id<TAB>category<TAB>title<TAB>file` line per match (exact id
first, then exact title, else substring on title).

- **One match**: use it.
- **Several**: list them and ask which one. Non-interactive: report the
  candidates and stop.
- **None** (interactive only): the task isn't in the backlog yet. Create it
  without asking. Classify it into `feat`/`fix`/`chore`/`refactor` (rubric in
  `skills/radin-record/SKILL.md`), then:

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

  Report the new entry, then continue with it as the scoped entry.
  Non-interactive: the scope always came from an existing entry, so no
  match means backlog drift. Report and stop instead of writing a
  duplicate.
- **Already planned**: `radin-backlog.sh meta "<id>"` prints one
  `plan<TAB><path>` line per existing pointer. If any, show the path(s) and
  ask whether to re-plan (overwrite) or stop. Stop unless confirmed.

Record the entry's `id` and `title`; the id is the `parent_id`.

## Step 3: Judge whether the scope should split

Invoke `/ponytail:ponytail` and apply its ladder: does this entry need more than one
plan? Lean toward NOT splitting. Split only when the entry genuinely
bundles multiple unrelated, independently plannable changes.

This is a judgment call about the user's own task, so surface it.
Interactive: state your read (split or not, and why) and confirm it, using
`/mattpocock-skills:grilling` when the entry's scope is genuinely unclear.
Non-interactive: take the default (no split) without asking.

- **Not splitting**: the sub-task list is the entry itself.
- **Splitting**: show the proposed sub-tasks (short titles, one-line
  description each, full coverage, no overlap) and confirm. Confirmed or
  edited: use that list. Rejected: fall back to the single-item list.

## Step 4: Write each plan

The entry's file (`$BACKLOG_TASKS_DIR/<parent_id>.md`) never moves, so no
re-resolution is needed between sub-tasks. For each sub-task, in order:

1. Read the entry's file. A sub-task from a split has only its one-line
   Step 3 description as scope, so plan just that part.
2. Explore the codebase: structure, affected files, patterns, constraints.
   If `code-review-graph` is wired for this repo, use its MCP tools
   (`semantic_search_nodes`, `get_impact_radius`, `query_graph`) before
   Grep/Glob/Read. Prefer `rtk`-wrapped commands when `command -v rtk`
   succeeds. If the plan hinges on third-party API or library behavior
   local code can't confirm, invoke `/mattpocock-skills:research` against
   primary sources first, and never guess at external behavior.
   Non-interactive: `/mattpocock-skills:research` spawns its own agent whose result
   you cannot count on receiving, so stop and report the unconfirmed external behavior
   instead of guessing or waiting.
3. Invoke `/ponytail:ponytail` and apply its ladder to produce the plan:
   - The minimum files to touch.
   - The concrete change in each file.
   - Order of operations, where it matters.
   - How to verify (tests/checks to run), because lazy code without its
     check is unfinished.

   Surface every open question the plan raised. Interactive: invoke
   `/mattpocock-skills:grilling` on the entry's open aspects. It walks the
   decision tree one question at a time, defers facts to repo exploration, and won't finalize
   until understanding is confirmed. The plan you hand off must leave zero
   decisions to whoever executes it. Non-interactive: an unresolvable
   question stops the run, so report it rather than plan around it.
4. Save the plan at `$NAMESPACE_DIR/plans/<sub-task-id>.md`.
5. Insert the pointer via the CLI (appends `**Plan:** <path>` to the task's
   file, after any earlier `**Plan:**` lines):

   ```bash
   RADIN_CLI backlog add-plan "<parent_id>" "$NAMESPACE_DIR/plans/<sub-task-id>.md"
   ```

6. Report: `✅ <sub-task-id> planned. Plan: <path>.`

Planning and executing are separate tools: edit no source file, run no
build/test, create no commit anywhere in this skill. Never touch the scoped
task's file beyond the appended `**Plan:**` line(s), and never touch any
other task's file.

## Step 5: Review each plan before handing it off

A plan is a proposal, so review it before `radin-execute` builds on it. For
each plan file just written:

1. Invoke `/thermo-nuclear` against the plan file's content (not the
   codebase): does the proposed approach itself carry a structural issue
   the rubric flags?
2. Invoke `/ponytail:ponytail-review` against the same file: speculative
   flexibility, reinvented stdlib, single-caller layers?
3. Fix each finding by editing the plan file in place. The fix belongs in
   the plan itself, and nothing goes to the backlog (unlike `radin-review`,
   this plan hasn't executed yet, so there is no review record to keep).
4. Zero findings: leave the file untouched.

## Step 6: Report back

```
✅ Entry planned.

| Sub-task | Plan | Review findings |
|------|------|------|
| <id> | $NAMESPACE_DIR/plans/<id>.md | <count of fixes applied, or "none"> |

Next: radin-execute (or a human) can implement from the plan(s) above.
```