rota

Examples

Each example is a situation and the skills rota reaches for in it. Every step shows what you type and what the agent prints.

Fix a small bug or add a small feature

One clear item, small enough to build in one sitting.

  1. /rota-capture Write the item down. Capture records it and stops.

    rota-captureillustrative, condensed
    /rota-capture the list command shows every row when I ask for zero
    [B03] list shows every row when the limit is zero   Bug, P2

  2. /rota-work Build it in small commits. The proof gate needs a red run, then a green one.

    rota-workillustrative, condensed
    /rota-work B03
    Tree clean. Branch rota/B03-limit-zero created.
T1  treat 0 as a real limit in cmd/list.go
    rota proof record B03 -- go test ./cmd -run TestListLimitZero   FAIL (red run)
    rota proof record B03 -- go test ./cmd -run TestListLimitZero   PASS
a1b2c3d fix: treat --limit 0 as zero rows [B03]

  3. /rota-ship Review the branch, then open the PR or merge.

    rota-shipillustrative, condensed
    /rota-ship
    /rota-review: PASS
PR body built from commit subjects and resolved IDs: B03
Merged into main with --no-ff; branch deleted.

The full walkthrough →

Build a bigger feature

A Major item where the design or the approach needs sign-off before code lands.

  1. /rota-capture Record the feature as an item.

    rota-captureillustrative, condensed
    /rota-capture "an /rota-archive command that ages out resolved items older than 90 days"
    [F12] /rota-archive command for old resolved items   Feature, Major
Run /rota-brainstorm F12 before /rota-plan to negotiate the design.

  2. /rota-brainstorm Settle the design with you, section by section.

    rota-brainstormillustrative, condensed
    /rota-brainstorm F12
    Read F12, KNOWLEDGE.md and DECISIONS.md.
Question: what signals "resolved"? ## Completed only, or also ARCHIVE.md?
    Completed only.
    Design drafted: 3 approaches with tradeoffs, recommended the append-only journal.
Approve and hand off to /rota-plan, approve with no plan yet, or revise?

  3. /rota-plan Turn the design into tasks with a way to verify each.

    rota-planillustrative, condensed
    /rota-plan F12
    Planning dial: 1 (pointers) - the design is signed off and revert is clean. Override: say "level 1" or "level 4".
Goal: /rota-archive moves ## Completed items older than 90 days into ARCHIVE.md.
T1. Append archived items to ARCHIVE.md in internal/backlog/archive.go.
    Verify: go test ./internal/backlog -run TestArchiveAppend
T2. Wire the command and the 90-day cutoff.
    Verify: go test ./cmd -run TestArchiveCutoff
Confirm this plan? (yes / changes)
    yes

  4. /rota-work Build the plan, one verified task at a time.

    rota-workillustrative, condensed
    /rota-work F12
    Tree clean. Branch rota/F12-rota-archive created. Plan .rota/plans/F12.md: 2 tasks.
T1  append archived items to ARCHIVE.md
    rota proof record F12 -- go test ./internal/backlog -run TestArchiveAppend   FAIL (red run)
    rota proof record F12 -- go test ./internal/backlog -run TestArchiveAppend   PASS
    c4d5e6f feat: append archived items to ARCHIVE.md [F12]
T2  wire the command and the 90-day cutoff   PASS
    d7e8f90 feat: add /rota-archive with a 90-day cutoff [F12]

  5. /rota-ship Review against what the item promised, then merge.

    rota-shipillustrative, condensed
    /rota-ship
    /rota-review: PASS (checked against the F12 design and its acceptance)
PR body built from commit subjects and resolved IDs: F12
Merged into main with --no-ff; branch deleted.

The full walkthrough →

Chase a bug you don't understand

Something is broken and the cause is not known yet.

  1. /rota-debug Reproduce it, test one hypothesis at a time, fix it in one commit.

    rota-debugillustrative, condensed
    /rota-debug F04
    Reproducer: TestAmountRoundTrip FAILED (0.10 -> 9, want 10)
H1 (likely): the minor-unit helper multiplies a float64 by 100 and truncates.
Verified H1: the intermediate float prints 9.999999999999998.
Fix: decimal Shift(2) instead of Float64() * 100. Reproducer passes.
fix(money): use decimal.Shift instead of Float64 for minor-unit conversion
Root cause was non-obvious. Consider running /rota-learn to capture this.

  2. /rota-ship Review and merge the fix.

    rota-shipillustrative, condensed
    /rota-ship
    /rota-review: PASS
PR body built from commit subjects and resolved IDs: F04
Merged into main with --no-ff; branch deleted.

  3. /rota-learn Keep what the bug taught you for the next session.

    rota-learnillustrative, condensed
    /rota-learn
    Proposed bullet under ## Money & Decimals:
Never multiply a decimal.Decimal by a float to convert to minor units. Float64() * 100 gives 9.999... for 0.10, and truncation gives 9. Use decimal.NewFromString(...).Shift(2).IntPart() end to end.
Written to .rota/KNOWLEDGE.md.

The full walkthrough →

Try a risky idea first

You don’t know yet whether an approach or a library works.

  1. /rota-spike Try it on a throwaway branch. Only the findings come back.

    rota-spike
    /rota-spike will a single-currency schema survive a later move to multi-currency?
    Question: can a single-currency schema migrate to multi-currency without data loss? Named it sqlite-schema.
Created branch spike/sqlite-schema and .rota/spikes/sqlite-schema.md.
The question is recorded. Experiment on the branch; fill in Findings and Decision when done.

  2. /rota-plan Plan the real work with what the spike found.

    rota-planillustrative, condensed
    /rota-plan M01-S01
    Planning dial: 3 (research round) - a schema migration does not revert cleanly; the spike already answered the open question. Override: say "level 1" or "level 4".
Read .rota/spikes/sqlite-schema.md: ship single-currency in M01, no currency column yet.
Goal: stand up the SQLite schema and tally add end to end.
T1. Skeleton CLI in cmd/tally.
    Verify: go test ./... && tally --version | grep v0.0.0
T2. Migrations engine in internal/store/migrate.go.
    Verify: run tally init twice; the second run is a no-op
...
Confirm this plan? (yes / changes)
    yes

  3. /rota-work Build it.

    rota-workillustrative, condensed
    /rota-work M01-S01
    Plan .rota/plans/M01-S01.md read: 5 tasks, none done. Branch rota/M01-S01 created.
T1  skeleton CLI in cmd/tally
    go test ./...                       PASS
    tally --version | grep v0.0.0       PASS
    feat(cli): scaffold tally root command
Next: T2 migrations engine.

The full walkthrough →

Start a project from a brief

An empty repo and an idea of where it should go.

  1. /rota-init Suggest config values from the repo, confirmed one by one.

    rota-init
    /rota-init
    test.fast = go test ./...   (from Makefile target `test`)
git.baseBranch = main       (from origin/HEAD)
forge.provider = github     (from the origin remote URL)
Set test.fast to `go test ./...`?  A) yes (recommended)  B) other
    A
    rota config set test.fast '["go test ./..."]'

  2. /rota-vision Turn the brief into milestones.

    rota-visionillustrative, condensed
    /rota-vision
    I found README.md (Tally). Seed milestones from it?
Your brief says "dogfood within two weeks." What does dogfooded mean concretely?
    a CLI I use daily for two weeks before showing anyone else
    Proposed: M01 CLI MVP, M02 Web dashboard (depends M01), M03 Budget alerts (depends M01).
M01 marked active.

  3. /rota-plan Plan the first milestone slice.

    rota-planillustrative, condensed
    /rota-plan M01-S01
    Planning dial: 2 (spec) - first slice of a new schema; a migration does not revert cleanly. Override: say "level 1" or "level 4".
Goal: stand up the SQLite schema and tally add end to end.
T1. Skeleton CLI in cmd/tally.
    Verify: go test ./... && tally --version | grep v0.0.0
T2. Migrations engine in internal/store/migrate.go.
    Verify: run tally init twice; the second run is a no-op
...
Confirm this plan? (yes / changes)
    yes

  4. /rota-capture Turn the plan into backlog items.

    rota-captureillustrative, condensed
    /rota-capture "tally CLI skeleton, sqlite migrations engine, transactions schema with int64 minor units, tally add command, tally list command"
    [F01] tally CLI skeleton                          Feature, Minor, Milestone: M01
[F02] sqlite migrations engine                    Feature, Minor, Milestone: M01
[F03] transactions schema with int64 minor units  Feature, Minor, Milestone: M01
[F04] tally add command                           Feature, Minor, Milestone: M01
[F05] tally list command                          Feature, Minor, Milestone: M01

  5. /rota-work Build the first item.

    rota-workillustrative, condensed
    /rota-work
    Backlog (M01 active): Features F01, F02, F03, F04, F05 (all Minor)
Suggested next: F01 (head of M01 dependency chain)
Run /rota-work F01? [y/N]
    y
    Branch rota/F01-tally-cli-skeleton. Plan task 1: skeleton CLI.
verify: go test ./...                      PASS
verify: tally --version | grep v0.0.0      PASS
feat(cli): scaffold tally root command [F01]
Merged into main with --no-ff; branch deleted.

The full walkthrough →

Bring rota into an existing project

A repo with history and a backlog that lives in your head, with no rota yet.

  1. /rota-init Suggest config values from the repo, confirmed one by one.

    rota-init
    /rota-init
    test.fast = go test ./...   (from Makefile target `test`)
git.baseBranch = main       (from origin/HEAD)
forge.provider = github     (from the origin remote URL)
Set test.fast to `go test ./...`?  A) yes (recommended)  B) other
    A
    rota config set test.fast '["go test ./..."]'

  2. /rota-refactor With –map, draft the project map so later cycles skip re-exploring the code.

    rota-refactorillustrative, condensed
    /rota-refactor --map
    Mapped 6 subsystems. Files to write:
  .rota/map/api.md           new
  .rota/map/dashboard.md     new
  .rota/map/alerts.md        new
  .rota/map/integrations.md  new
  .rota/map/storage.md       new
  .rota/map/shared.md        new
Write the new files? (all / pick / none)
    all
    Wrote 6 files, skipped 0. Ran rota map index and rota map stats.

  3. /rota-capture Brain-dump the bugs and ideas you have been carrying around.

    rota-captureillustrative, condensed
    /rota-capture "alert rule editor crashes on empty title; we should add a /health endpoint for k8s; dedup window is hardcoded at 5 min, should be per-rule; DST off-by-one on dashboard 24h filter"
    [B06] alert rule editor crash on empty title  Bug, P1, Major
[F01] /health endpoint for k8s probes         Feature, Minor
[F02] per-rule dedup window                   Feature, Major
[B07] DST off-by-one on dashboard 24h filter  Bug, P1, Major
F02 is Major: consider /rota-brainstorm F02 before /rota-plan.

  4. /rota-work Take the P0 first. The map and knowledge tell the worker where to look.

    rota-workillustrative, condensed
    /rota-work B05
    Read .rota/map/integrations.md. KNOWLEDGE.md has nothing under Security yet.
Branch rota/B05-secrets-in-url-form created. 4 tasks.
T1  render secrets via <input type="password">
    rota proof record B05 -- npm test -- integration-form   PASS
T2  reject secrets in the URL query on the POST endpoint
...

  5. /rota-debug When a fix will not stay fixed, find the cause before changing code.

    rota-debugillustrative, condensed
    /rota-debug B01
    Reproduced: TestDedupAcrossIntegrations fails, two events instead of one.
Hypothesis: dedupKey includes severity, and the integrations differ in casing.
Verified before touching code: lowercased severities give matching keys.
Fix: lowercase severity in the dedup-key computation. Reproducer passes.
fix: normalize severity casing in dedup key [B01]
Non-obvious cause: run /rota-learn to save this gotcha.

  6. /rota-learn Keep the gotcha so the next cycle in that area starts with it.

    rota-learnillustrative, condensed
    /rota-learn
    Proposed bullet under ## Alerts:
Severity is case-sensitive in the dedup key path. Normalize at the boundary, not at storage time.
Written to .rota/KNOWLEDGE.md.

The full walkthrough →

Run several issues in parallel

A few independent issues are ready and you can stay around for questions.

  1. /rota-plan Shape the slate so every issue has clear acceptance.

    rota-planillustrative, condensed
    /rota-plan 42
    Planning dial: 2 (spec) - new flag on a published command; revert is clean. Override: say "level 1" or "level 4".
Goal: export --since DATE keeps only rows on or after DATE.
T1. Parse and validate --since in cmd/export.go (AC-1).
    Verify: go test ./cmd -run TestExportSince
T2. Document the flag in docs/usage/export.md (AC-2).
    Verify: grep -n -e --since docs/usage/export.md
Confirm this plan? (yes / changes)
    yes

  2. /rota-orchestrate Hand issues to workers, review their PRs, merge through the gate.

    rota-orchestrate
    rota orchestrate
    run a round on issues 42, 51, 58 and 63
    rota round start --scope slate --items 42,51,58,63
rota round assign 42   # claims #42, cuts <agent>/42-<slug>, starts a worker
...
Armed rota round watch in the background; it wakes me on a slot, PR or escalation change.

  3. /rota-answer Answer the decisions the round put to you, one at a time.

    rota-answer
    /rota-answer
    1 of 3: slot nia is blocked on #58.
Worker asks: keep the old --json shape or break it?
A) Keep the old shape (recommended)
B) Break it and note it in the changelog
C) Write your own answer
    A
    Recorded as a decision comment on #58 and relayed to nia.

  4. /rota-learn At wind-down, keep what the round learned.

    rota-learnillustrative, condensed
    /rota-learn
    Read the round summary: #58 bounced twice on the same criterion.
Proposed bullet under ## Rounds:
A criterion with two readings produces the same wrong PR on every bounce. Audit the acceptance criteria before the third relay.
Written to .rota/KNOWLEDGE.md.

  5. /rota-release Cut a release when the work adds up to one.

    rota-release
    /rota-release
    Checklist (.rota/RELEASE.md): all items pass.
Commits since v0.25.0: 1 feature, 4 fixes. Recommend minor.
    minor
    Release notes drafted for v0.26.0.
Notes look good? Yes pushes the tag and publishes the release. (manual gate)

The full walkthrough →

Stop for today

The context is filling up or you have to leave mid-item.

  1. /rota-learn Save the lessons worth keeping.

    rota-learnillustrative, condensed
    /rota-learn
    Proposed bullet under ## Timer:
The badge reads its count from the store on mount, so a stale subscription shows the previous value until the first tick. Re-subscribe in the quick-switch handler.
Written to .rota/KNOWLEDGE.md.

  2. /rota-pause Write a handoff so a fresh session continues.

    rota-pause
    /rota-pause
    Uncommitted work on rota/fix-B07-timer-badge: wip commit, stash, or leave in place?
    wip commit
    Paused rota/fix-B07-timer-badge - handoff note saved.
Resume with /rota-work in a fresh session.

  3. /rota-work Next session, with no argument, it reads the handoff and picks up.

    rota-workillustrative, condensed
    /rota-work
    Active streams
  rota/fix-B07-timer-badge  (1 wip commit)  mid-implementation

Handoff note found:
  Next planned step: re-run the badge test after the selector change

Resume with /rota-work, or leave the handoff for later?
    resume
    Resuming /rota-work with handoff brief.