loom-plan-writer

Loom Plan Writer

THE REQUIRED SKILL FOR CREATING LOOM EXECUTION PLANS. Invoke it whenever an agent needs to author a plan for loom orchestration.

A loom plan is a DAG of stages that loom runs in isolated git worktrees. It maximizes throughput with two levels of parallelism — subagents within a stage (FIRST priority) and concurrent worktree stages (SECOND) — and it is only as good as its CLAIMS about the code are TRUE and its verification actually PROVES them.

This skill assumes CLAUDE.md is in context (it always is under loom). Where CLAUDE.md already governs something — subagent preambles (Rule 5), hierarchies (Rule 6), memory routing (Rule 12/18), branch discipline — this skill points at it rather than restating it.

Two rules dominate everything below:

1. Ground every claim before you write it (Section 1) — the #1 cause of bad plans.
2. The plan file is your deliverable. After writing it, STOP (Section 11) — never implement.

1. Ground Every Claim (READ THE SEAM)

⚠️ A plan is a set of CLAIMS about code: "this function does X," "this enum's consumers are Y," "this field is safe to add," "this command type-checks." Every claim is WRONG until the code confirms it. The design spine is usually sound — defects hide in UNREAD seams. A file the plan NAMES is a promise to read; a described file is an unread file.

Before any stage description, acceptance, artifacts, wiring, or wiring_tests asserts anything about a seam, OPEN that seam and read it to the bottom. Never assert from memory, a sibling repo, a plausible filename, or "it usually works this way." The repo's own incident/runbook docs are PRIMARY — read the one the user has open before encoding an external system's behavior from memory.

VERIFY-BEFORE-WRITE CHECKLIST — run for every stage:

□ Every file the stage NAMES, I have OPENED (not inferred from its name).
□ Every symbol the stage CHANGES, I grepped for every importer/consumer across
  the WHOLE repo (BOTH packages in a monorepo) — and followed each edge ONE ring
  out (callers/renderers I did not already think of).
□ Every behavior the stage ASSERTS (a guard enforces X, an error code is
  terminal, a field is safe, a command type-checks) — I read the implementation
  that provides it, including catch-alls and branch ORDER.
□ Every value/behavior the design LEANS ON, I read the line that PRODUCES it (not
  the type/schema/getter that DESCRIBES it) AND confirmed it holds in EACH
  environment that runs the code (prod vs dev, build-time vs unit-test vs e2e,
  container env set, same-origin vs cross-origin). "The symbol is defined" ≠ "it
  holds the right value in the runtime that executes THIS code."
□ Every RULE the plan states about ONE site ("reset this global here," "keep env
  clean for this boot path") — I grepped its structural SIBLINGS (same-shape
  modules, every importer) and applied it to ALL in the same pass, not as a
  one-off note.
□ Every message / limit / line / count / status code / external behavior /
  package dependency is READ from its source, never recalled.
□ No claim rests on memory, a sibling repo, or a plausible name.
□ Every claim about a SIBLING PLAN's surface (upstream symbol, consumer seam,
  file owner) passed the Cross-Plan Contract Protocol — verified against
  committed code or the sibling's stage YAML, never its prose.