rota-decide — Capture Hard-Boundary Decisions

Distill an active commitment from the session into .rota/DECISIONS.md, by topic, so future work treats it as a hard constraint. Decisions are active (boundaries with forbids/permits); /rota-learn captures passive knowledge (gotchas, conventions).

Copy this checklist and track your progress:

- [ ] Step 1 — Mode (default vs source-prefill)
- [ ] Step 2 — Identify the Candidate Decision
- [ ] Step 3 — Compose the Four Parts
- [ ] Step 4 — Classify by Topic
- [ ] Step 5 — Confirmation Gate
- [ ] Step 6 — Merge into DECISIONS.md
- [ ] Step 7 — Update the Decisions Index
- [ ] Step 8 — Confirm

Step 1 — Mode (default vs source-prefill)

• No flag — default mode: Step 2 elicits the candidate conversationally.
• --from-learning <topic> — Source-Prefill Mode (Learning): Step 2 seeds the draft from .rota/KNOWLEDGE.md.
• --from-spike <name> — Source-Prefill Mode (Spike): Step 2 seeds the draft from .rota/spikes/<name>.md.

Both flags together is invalid: error with "/rota-decide accepts at most one of --from-learning <topic> or --from-spike <name> per invocation." and stop.

Step 2 — Identify the Candidate Decision

A decision must be active (committed; violating it is a regression), bounded (forbids X, permits Y) and justified (a why: incident, deadline, stakeholder ask).

Three-gate trigger (pre-write check). All three must pass to proceed past Step 2, in every mode (default, --from-learning, --from-spike):

(a) Hard to reverse. Undoing needs coordinated edits across many files, retraining habits or data migration. git revert plus a small refactor means preference, not decision.

(b) Surprising without context. A future contributor would not infer the rule from existing patterns. If the codebase already documents it, it's a convention.

(c) Real trade-off. Genuine alternatives existed and the project deliberately passed on them. One option only means a default, not a decision.

If any gate fails, do not write to DECISIONS.md. Surface to the user:

"This reads like a [preference / convention / default] rather than a hard boundary — gate (X) failed. Run /rota-learn to capture it as durable knowledge instead, or leave it inline at the call site."

Substitute the failing gate's letter for (X); suggest /rota-learn if a learning is worth keeping, else "leave inline", and stop. Do not auto-invoke /rota-learn: same manual-gate policy as the no-forbids/no-permits redirect below.

Default mode.

Surface a clear candidate from the conversation; if none, ask:

"What boundary do you want to lock in? State it as one sentence — what the decision says."

Ground the boundary with references/grilling.md: pin the rule's terms, then grill forbids and permits as numbered questions with a recommended answer each, answering from code first and testing the edges with a scenario. Stop at an empty frontier.

If after one round the user can't articulate forbids or permits, it's a learning, not a decision: suggest /rota-learn and stop. Do not auto-invoke /rota-learn; the user re-runs it deliberately.

When invoked with --from-learning <topic> or --from-spike <name>, read `source-prefill-modes.md`, then continue to Step 3.

Step 3 — Compose the Four Parts

Every decision entry has four parts:

1. Rule — one-sentence statement of what the decision says
2. Why — one paragraph (incident, constraint, deadline, ask)
3. Forbids — concrete patterns, files, approaches ruled out
4. Permits — what this still allows (keeps the boundary from over-applying)

Draft all four from conversation context. One AskUserQuestion only when a part is genuinely ambiguous; otherwise show the draft and let Step 5 handle approval. In source-prefill modes Step 3 is the user's chance to redline.

Step 4 — Classify by Topic

Reuse existing ## Topic headings in .rota/DECISIONS.md, then KNOWLEDGE.md topics (Architecture, Testing, Build & Tooling, …) so one name maps to both files. New topic only if nothing fits; keep topics coarser than learnings.

Step 5 — Confirmation Gate

Present the assembled entry to the user via AskUserQuestion:

• Header: "Decide"
• Question: "Lock in this decision?"
• Options (single-select):
  1. "Write it (Recommended)" — "Append to .rota/DECISIONS.md under <topic> and update the decisions index."
  2. "Edit first" — "Show the draft inline so you can rewrite any of the four parts before writing."
  3. "Cancel" — "Skip — nothing is written."

Show the full draft (rule, why, forbids, permits) above the question. Write only on an explicit "Write it"; anything else cancels. Edit first takes revisions and re-asks. Cancel stops with "Decision not captured."

Step 6 — Merge into DECISIONS.md

Format of .rota/DECISIONS.md:

# Decisions

Hard boundaries for this project. Each entry is a commitment, not a preference — re-read before proposing changes that touch its area.

## <Topic>

### <Decision title>

<One-sentence rule.>

*Why.* <One paragraph rationale.>

**Forbids.** <Concrete patterns/files/approaches.>

**Permits.** <What this still allows.>

<!-- 2026-05-01 -->

Merge rules:

• Never rewrite sections you didn't change; use Edit, not Write.
• Insert new ### Decision title blocks at the top of their topic (newest first).
• Stamp today's absolute date as <!-- YYYY-MM-DD -->.
• New topics go alphabetically, except Architecture and Build & Tooling may be pinned near the top (as in KNOWLEDGE.md).

Step 7 — Update the Decisions Index

rota block decisions

Updates the managed <!-- rota-decisions-start --> block in the project instructions file (AGENTS.md if present, else CLAUDE.md; the verb resolves it, never hardcode). The read-site skills (/rota-work, /rota-debug, /rota-plan, /rota-refactor, /rota-review, /rota-vision) read this block to know when to consult DECISIONS.md.

Step 8 — Confirm

Report in one compact block:

Captured 1 decision into .rota/DECISIONS.md:
  Architecture — "Background jobs run in-process, never via external queue"

Updated the decisions index in <AGENTS.md|CLAUDE.md> — /rota-work, /rota-debug, /rota-plan, /rota-refactor, /rota-review, /rota-vision will consult it.

If the entry created a new topic, prepend a line: "New topic: <topic>."

Key Principles

• Never auto-invoked. Regardless of autonomy.level; Step 5's confirmation is the only gate. Manual confirmation is the verification: no verifier runs.
• One sentence rule, one paragraph why. More: link a plan or knowledge entry.

References

• `references/grilling.md` — Frontier-round questioning for forbids/permits.
• `references/subagent-dispatch.md` — the light subagent that grilling sends for broad reads.
• `references/persistence-skills.md` — Shared spine and divergence axes for the persistence duo (/rota-learn, /rota-decide), including /rota-learn --term for Glossary entries.
• `references/source-prefill.md` — Source-prefill / promote-between-artifacts semantics for /rota-decide.
• `source-prefill-modes.md` — Source-prefill seeding rules and mode-to-section table.