Scenarios

Scenarios

Common workflow walkthroughs.

---

Scenario 1: New feature request

User says: "Add dark mode toggle"

Expected flow:

1. Agent reads .saipen/STATE.md and BOARD.md
2. If no active ticket -> propose one via PLAN or ADD
3. SCOUT the ticket: read existing UI code, find color theming
4. BUILD: implement toggle with minimal changes
5. VERIFY: toggle works, persists, reverses
6. REVIEW: diff check, backwards compat
7. SHIP: commit with conventional message
8. DONE: checkpoint

---

Scenario 2: Bug report

User says: "The export button crashes on empty state"

Expected flow:

1. HUNT or direct bug ticket
2. SCOUT: reproduce the crash, find relevant code path
3. BUILD: fix the null-pointer / missing guard
4. VERIFY: export works on both empty and populated states
5. REVIEW: check no side effects
6. SHIP: commit with fix reference

---

Scenario 3: Context handoff (cross-agent)

Scenario: Agent A worked for 2 hours, reached SHIP on T-42. User opens a different agent (Agent B) and says "saipen continue"

What happens:

1. Agent B reads BOOT.md -> STATE.md (phase: SHIP) -> BOARD.md (T-42 in DOING) -> LOG.md tail
2. STATE.next_action says "Complete SHIP for T-42: verify, commit, push"
3. Agent B picks up exactly where A left off
4. No briefing needed — the .saipen/ directory IS the brief

---

Scenario 4: Collaborative subSaipen

Scenario: Core agent working on main feature. User says "saihunt" to delegate a bug sweep.

What happens:

1. saihunt subSaipen auto-spawns with read-only mode
2. Runs 6-category HUNT sweep against current HEAD
3. Writes findings to kitchen/OUTBOX.md
4. Core agent collects OUTBOX, tickets findings
5. Main work never interrupted

---

Scenario 5: Goal mode sprint

User says: "saipen goal make the UI responsive"

What happens:

1. PLAN generates ticket wave (up to 20 tickets / 3 waves)
2. Each ticket goes through SCOUT -> BUILD -> VERIFY -> REVIEW -> SHIP
3. After each DONE, agent checks goal caps
4. If cap hit -> report progress, wait for user re-invoke
5. If mature exit -> final report, goal_mode disabled

---

Scenario 6: Post-crash recovery

Scenario: Agent crashed mid-BUILD. .saipen/ has stale state.

What happens:

1. New agent reads BOOT.md -> STATE.md (phase: BUILD, but stale claim_time > 15 min)
2. RFC § 1.5 Recovery: reset stale claim, reclaim ticket
3. LOG a RECOVERY: event
4. Resume SCOUT or BUILD depending on what was done

---

Scenario 7: Translation round

User says: "saipen translate"

What happens:

1. TRANSLATE phase loads
2. Agent reads EN root docs + existing .saipen/saitranslate/kitchen/
3. Detects drift since last run
4. Core locales (RU/ET/DED) updated by main agent
5. 29 non-Core locales ticketed for subSaipen instances
6. Completion LOGged, bundle sits in kitchen awaiting integration

---

Scenario 8: Clean sweep

User says: "saipen clean"

What happens:

1. CLEAN phase loads
2. Board scrub: prune done tickets, fix structural issues, check BLOCKED items
3. Orphan hunt: find and delete unconnected files
4. Link audit: fix dead references
5. Trash removal: temp files, caches, stale kitchen files. Seal LOG if oversized.
6. Freshness check: verify paths and dependencies
7. LOG completion, STATE -> DONE