radin-record

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Record to Backlog

## Step 1: Decide what to log

The instruction sets the scope:

- **Specific**: "add the auth timeout bug", "fix this issue", "work on adding that feature"
- **Generic**: "add the findings", "record everything", "we should probably": scan the whole
  session for anything a reasonable person calls a bug, follow-up, idea, or feedback.
  Each distinct item becomes its own entry.

Log the entry worded close to how it was raised.

One raised thing can be several sequential pieces of work ("add rate limiting on
top of new auth middleware" needs the middleware first). Log each piece as its
own entry, sized as a **vertical slice**:

- It cuts a narrow but complete path through every layer it touches.
- Landed, it is demoable or verifiable on its own.
- It fits one fresh context window.
- A **prefactor**, the restructuring that makes the real change easy, is its
  own entry, which every entry needing it depends on.

One mechanical change whose blast radius fans across the codebase is the exception,
so log it as one entry per batch the change breaks, plus a final
entry that puts the tree back green depending on every batch.

An item too fuzzy to phrase as a sharp question is a **stub** ("figure out
caching at some point"): log one stub over the whole area, its body saying what
is unspecified and what is known, rather than pre-slicing it. Step 2
sharpens it later. A question you *can* state precisely is an ordinary entry,
blocked or not.

### An external ticket as context (optional)

A ticket key, Jira or GitHub issue URL: fetch it through its MCP,
and treat the ticket as extension to the user's prompt.
No MCP or API access: log from the ask alone, and continue.

## Step 2: Chart each item's open decisions

Settle judgment calls here, while the user is present.

Apply `RADIN_LIB/radin-open-decisions.md` to each item. Look up each Fact now in the
repo, its docs or the API, and keep the answer for Step 5's body. Ask the item's
Decisions now, before the next item and before Step 5's list. Keep every settled
answer for Step 5's body. An item with no Decision asks nothing, and so does a stub,
one deliberately deferred whole.

**Why:** `radin-batch` cannot ask mid-run, so every question left in an entry stalls
that run. The user is present now and the batch is not.

Pick the channel by the Decisions:

- **Up to 4 Decisions, each with discrete options:** one `AskUserQuestion` call.
  Put your recommendation first, marked "(Recommended)".
- **More than 4, open-ended answers, or answers that depend on each other:** invoke
  `/mattpocock-skills:grilling` on them.

**The test:** does Step 5's list show a question for the user to answer? Then it
belongs here. Step 5 asks only whether the split, the dependencies and the plan
verdicts are right.

A Decision stays open only when the user says "later" or does not answer, or when
no user is present to ask (a sub-agent runs this skill). Then record it as one body line,
`**Open decision:** <question>, <options>, <your recommendation>`, so
`radin-batch` asks it before execution instead of guessing.

## Step 3: Note any skill invoked for this item

If the request that raised the item explicitly invoked a skill (e.g.
`/radin-record /frontend-design make the accent color...`, or a skill ran earlier
and the item continues that work), record it as a standing instruction, even if it
looks redundant or wrong-fit to you: without the line a cold start re-implements
from bare text and never invokes the skill the user chose.

`/radin-record /other-skill <...>` means "record an instruction to run
`/other-skill` later", and never run `/other-skill` now. Treat `/other-skill
<...>` as the text to log: go to Step 1 with it as the item, log with
`--skill other-skill`, and stop.

## Step 4: Classify each item and note dependencies

Does landing this item require another item in the batch (or an existing backlog
task) to land first, by sharing a file/function/behavior or by an explicit
build-on? Note the other entry's exact title for Step 5's `set-deps`, and say why
it comes first in the dependent entry's description. The `depends_on` field
carries the ordering, the prose the reason.

Classify into exactly one category (conventional-commit vocabulary):

- **feat**: a new capability asked for (idea, feature request).
- **fix**: something broken or behaving incorrectly.
- **chore**: a maintenance follow-up (docs, tooling, cleanup).
- **refactor**: structure should change without behavior change.

Then group. Two or more items in the batch that serve one feature, goal or
raised thing form an **epic**. Run `RADIN_CLI backlog epics` first. When an existing
epic already covers the goal, reuse it. A lone item gets no epic.

**The test:** would each body repeat the same background, the same `**Raised as:**`
quote or the same constraint? Then it belongs in the epic.

Then judge whether the item needs a plan before execution. Judge by `RADIN_LIB/radin-planning-rule.md`. An entry that needs no plan goes to an execution sub-agent, which implements from the entry alone.

Size each entry that needs no plan by `RADIN_LIB/radin-complexity-rule.md`. The
planner sizes an entry that needs a plan.

## Step 5: Append via the CLI

**Append right away.** Never ask the user to approve the granularity, the
dependencies, the split or the plan verdicts. Step 6 reports them, and
`radin backlog` edits a wrong entry afterwards.

**Why:** a confirmation gate stalls a capture the user already asked for, and a
user who closes the window logs nothing.

An entry carries its decisions, or names what stays open. Literal content in the
ask, such as an error string, a path, a snippet or an explicit constraint, belongs
in the `**Raised as:**` quote before anything is appended.

From shortcuts/radin, MIT.

More from shortcuts/radin