figure-it-out

name	figure-it-out
description	Design and run an auditable playbook when no narrower one fits: scaled rigor, a hypothesis loop, and a logged decision trail. Use for /figure-it-out, 'figure it out', a large migration, or unattended work a human reviews later. Use software-engineering for the architecture plan itself.

Figure It Out

When no playbook matches, design one. First deliverable is a phase sequence that scales rigor, runs the scientific method, and leaves a decision trail a human can audit after stepping away. Bias toward rigor because wrong work costs more.

Do not reinvent a playbook you already have. Route a focused single-unit task to its matching playbook: bug fix, performance, feature, visual parity, evaluation, or multi-phase plan. Use this skill for the large or cross-cutting version of one, such as a migration across many call sites, an ambitious multi-part change, or work the user reviews after stepping away. The rigor and the audit trail are the point.

Open a todolist with the phases below as items.

Phase A: Frame

Do not start the run until you can state:

• The definition of done as a falsifiable predicate (the prove-it-works principle in engineering-principles). "Done well" has to be checkable.
• Scope, quantified: rough units and effort, plus the blockers grounding surfaced. Raise blockers before spending hours, not after fifty doomed commits.
• The rigor level, biased high. One-way doors and a wide breakage surface earn more rigor. Reversible low-stakes steps earn less. Rigor means gates and artifacts, not "try harder".

Present the framing and tradeoffs before committing to a long run. Reversible work proceeds without asking, but a multi-hour run earns one checkpoint.

Phase B: Design the workflow

Decompose the task into atomic, independently landable units. Before writes, use git-toolkit to plan the stack and its rollback boundaries. Sequence the riskiest unknown first. Build scaffold and verification before features.

• Build the verification harness before the work. Capture the baseline from the pre-change state so each check reads as old value against new value.
• For one-way-door design decisions, run architect, which runs arena, with diverse, isolated, opinionated candidates and a read-only judge on a different model family. Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the laziness-protocol principle in engineering-principles).
• Decide what fans out. Parallelize only across genuine seams. Give each parallel worker its own worktree or branch so no two workers share mutable state. Do not over-fan.
• Write the designed phase list down. The human reviews that list.
• When the run spans sessions or risks compaction, persist the designed phase list and the findings through planning-with-files.

Then put the design into motion. Add its steps to the todolist as concrete items, after the Phase C entry and before Phase D. Run each step under the Phase C loop discipline. Weave the Phase D log through the steps, one row as each step lands, instead of saving the whole trail for the end.

Phase C: Run the loop

This skill owns the program lifecycle, hypotheses, and audit trail. verified-slice stays a unit method and does not own program lifecycle, architecture, or audit trail.

State the hypothesis and predicate. Then run each planned unit through the verified-slice method in engineering-principles. It handles baseline, implementation, proportional verification, review, correction, and exact candidate preparation. With local-commit, commit the candidate, then confirm occurrence. Otherwise, hand off the exact patch and stop. Start the next unit only after a confirmed occurrence and durable rollback boundary.

Inspect the real artifact, never a self-report. Pair delegated work with a judge and audit its artifact. Use VERIFIED, NOT_VERIFIED, or INCONCLUSIVE. An inconclusive result does not pass.

Phase D: Keep the audit trail

Log the run through show-me-your-work: one canonical TSV with a row per decision and per unit, evidence as links. Work run under this skill is usually ambitious enough to commit the trail so the reviewer reads it in the pull request. Commit the trail when confidence has to be shown. Prefer evidence produced by committed scripts so a reviewer can re-run it. The trail plus the diff is what lets the human come back and trust the work.

Phase E: Verify and hand back

Check the whole against the Phase A predicate on the real product, not only the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script so the win cannot silently regress (the encode-lessons-in-structure principle in engineering-principles).

Reply: the playbook you designed, the rigor level and why, the decision-trail path, what is verified against the predicate, and what is still open.