Skip to content

The five paths

A path is a route through spp's skills, from the situation you start in to merged work. There are five, and each one below lists its steps in order with the skill that runs each step. ask-spp places you on one when you are unsure which.

Path Start here when
1. Epic A change is too large for one session, and you can see how to get there
2. Single issue Someone filed a bug or an enhancement
3. Unknown territory An effort is too large for one sitting, and the way there is not visible yet
4. Scans Code resists change, you want a pull request's shape judged, or a suite carries tests that add no evidence
5. Tiny unfiled work One session finishes the change, and nothing is filed

Every path but the last needs the repo set up once with setup-spp, which writes the labels and the Routing block the other skills read.

1. Epic

If you have an idea that is not yet a plan, you can first explore it with discuss, an experimental skill. The step is optional, and you can skip it when you already know what you would build.

  1. Grill the plan. grill asks until every choice is settled, recording terms and decisions as they land. auto-grill runs the same interview but settles, with a citation, each question the code, ADRs or docs already answer.
  2. Write the spec. to-spec turns the conversation into one Epic issue, asking nothing new.
  3. Cut the Sub-issues. to-tickets splits the Epic into vertical Sub-issues with blocking edges, and calls harden to give each one its Ticket contract.
  4. Build. build hands the Epic to building, which dispatches workers in Waves, each running implement-issue in its own worktree. review gates every slice pull request, and building merges the ones that pass in dependency order. Follow it on the epic board.
  5. Gate the pull request to main. building picks the gate by size. A small Epic gets the review spec verdict. One with four or more Sub-issues, any size L Sub-issue, or 1,000 or more changed lines gets review-panel.
  6. Merge. You merge the pull request to main; no skill does.
  7. Close. close-epic writes the Epic's summary and retro comments, then records what it taught.

2. Single issue

  1. Triage. triage gives the issue a triage role and, when it is ready to build, calls harden to write its Ticket contract and size it. A bug's reproduction becomes its Verify block, red on main until the fix lands.
  2. Build. build hands the issue to building, which runs one worker, which builds the One-off with implement-issue (and diagnosing-bugs for a bug, with the Verify block as its loop), then one review gate.
  3. Merge. You merge the pull request.

3. Unknown territory

If the idea is still too loose to chart, you can first explore it with discuss. The step is optional, and it is not a path of its own, because a discussion may end in nothing.

  1. Chart the map. wayfinder turns a loose idea into a map of decision tickets on GitHub Issues.
  2. Settle one decision per session. Each ticket's label says how it settles: an interview with grilling, a cited note from research, a prototype, or one piece of manual work. Keep going until no decision stands between you and building.
  3. Join the Epic path. Once the map has a destination, to-spec in that conversation writes the Epic, and path 1 continues from step 3.

4. Scans

  1. Scan. improve-architecture surveys for deepening opportunities across the repo or in one pull request, and explores the one you pick, using the words of codebase-design. test-audit reads a suite for Pruning opportunities: tests another test already covers.
  2. File. Each skill files what you accept as an issue.
  3. Build it on another path. A filed issue small enough for one pull request takes path 2; a larger one takes path 1. A test-audit issue is always one test's removal, so it takes path 2.

5. Tiny unfiled work

No spp. Make the change in the session, with tdd if you want it test-first and pr for the pull request body. A change that grows past one session goes back to path 1 or path 2.