/phase-design

name: phase-design
description: How to decide what phases this project actually needs, when you're sketching PLAN.md or revising it mid-flight. Use this skill whenever you need to design, evaluate, or revise phases for a John project — phases are John's horizontal axis, suggestions not enforcements, and getting them right is what makes ralph-loop work.
metadata:
  triggers:
    - design phases
    - what phases
    - decide phases
    - phase boundary
    - phase plan
    - subdivide phase
    - merge phases
    - drop a phase
    - insert a phase

phase-design

You are the John-equipped agent designing phases for the user's project. The phases will live in `<project>/PLAN.md` and drive every loop iteration via [[ralph-loop]].

**Phases are suggestions, not enforcement.** John's stance is phases-as-skills with template override room — the engine doesn't gate on phase boundaries; the floor is disk-verifiable artifacts (see [[workspace-discipline]]). You're designing scaffolding that helps work decompose cleanly, not laws that punish deviation. Templates may radically reshape the phase list; users may request changes mid-flight; corpora may surprise you. Stay wide.

A phase is a unit of work with three properties:

1. **An intent.** One sentence. "Extract all rules from the regulation corpus." "Build the runtime UI shell." If you can't say the intent in a sentence, the phase is too big or too unclear. 2. **Disk-verifiable done criteria.** Specific paths/files that must exist, with optional content checks. Not "feels done." Not "the agent says it's done." See [[workspace-discipline]]. For fan-out phases that produce knowledge entries, the done criteria should name an **expected entry count or range** (derived from the corpus survey, recorded in PLAN.md) — that number feeds the reducer's deterministic count gate (`reduce_events.py --expect-entries`, see [[event-log-and-reducer]]), which refuses phase advancement on a large shortfall. 3. **A clean compaction point.** When you finish a phase, the world is in a state where context could compact (or the session could restart) and the next iteration could pick up cleanly from disk.

Phases that don't have all three are not phases — they're tasks within a phase, or arbitrary stopping points, or something else.

How many phases

For the knowledge phases (knowledge engineering): typically 4-8 phases. The starter from John (parse → survey → schema-design → chunk → extract → rewrite → package) is 7. You can drop or merge — for example, a corpus that arrives pre-chunked skips "parse" and "chunk."

For the app phases (app building): depends entirely on what's being built. A static-output app (slides, a wiki, a portfolio) might be 3-4 phases; an interactive runtime (a game, a verifier) might be 6-10. The active template usually suggests phases; if not, design them with the user.

Total across both halves: usually 8-15 phases for a moderately ambitious project. Fewer means the matrix isn't decomposed enough; more means you've over-sliced and the iteration overhead dominates.

Suggested knowledge phases

These are starting points, not requirements. The user or the active template overrides; treat the list below as a default to adapt, not a fixed sequence.

| # | Name | Why it might exist | Why it might not | |---|---|---|---| | 1 | parse | Raw input → markdown. PDFs need ppx, others need MarkItDown. | Corpus arrives as clean text already. | | 2 | survey | Read the corpus shape before designing anything. | Tiny corpus where you can read all of it in one pass. | | 3 | schema-design | Decide knowledge format/schema. | Active template has already fixed the schema. | | 4 | chunk | Break large docs into tree of progressive-disclosure chunks. | Short-file-set corpus needs onion-*wrapper* (assemble) instead — see [[chunking]]. | | 5 | extract | Sweep chunks for knowledge entries. Subagent fan-out. Open with a **schema pilot** (diverse 10–20 chunk sample against the draft schema, per [[schema-design]]) before committing the full fan-out; for large corpora the pilot can be its own thin phase. | Knowledge IS the corpus (e.g., already-structured data). | | 6 | rewrite + cross-link | Progressive disclosure, dedup, cross-link. | Single-entry corpus. | | 7 | package | Emit byte-identical SKILL.md trees to `<project>/.claude/skills/` and `<project>/.agents/skills/`. | Knowledge goes somewhere else (e.g., a database). |

When deciding knowledge phases for a specific project, walk this list and ask "does this project need this phase?" Drop or merge accordingly.

Long-docs vs short-file-sets: the onion decision

The chunking step has two opposite operations depending on corpus shape:

• **Onion-peeler** (default): one large document → tree of progressively-disclosed chunks. Break the doc down by header hierarchy + token budgets.
• **Onion-wrapper**: many small files → assemble them into a tree by domain/topic/folder. Same progressive-disclosure shape, opposite operation.

Quick rubric (decide in the **survey** phase, before chunking starts):

• One large document (textbook, regulation, long article) → peeler.
• Many small files (folder of 500 short memos, set of tweets, nested folder of snippets) → wrapper.
• Mixed (some long, some short, often the case for messy real-world input) → hybrid: peel the long ones, wrap the short ones, merge at chunk-tree boundaries.

This decision must be visible in PLAN.md's chunk phase (or whatever you name it). Don't defer it to the chunking skill — by the time chunking starts, the phase shape is already locked.

Suggested app phases

These come from the conversation about app mechanism, not from a fixed list. But common shapes:

• **Static-output apps** (slide deck, portfolio, wiki): scaffold → assemble content per entry (fan-out) → render → preview-iterate → publish.
• **Interactive runtime apps** (game, quiz, simulator): scaffold → wire core mechanics → seed content from knowledge → wire runtime LLM proxy (if needed)