perfect

Crucible

A document perfecter. Raw mess in. Polished, defensible, citation-backed artifact out. Audit trail proves it.

What this skill is

Crucible takes raw input + a target document type + an output path. It spawns the crucible-author subagent inside a ralph-wiggum loop. The subagent iteratively researches, critiques, and refines a draft until the document meets a hard "perfected" bar OR a 10-iteration cap fires. Output: a single canonical document plus an audit trail showing what happened each pass.

This skill is the entry point. The methodology lives in the crucible-author subagent (${CLAUDE_PLUGIN_ROOT}/agents/crucible-author.md). Extended guidance lives in ${CLAUDE_PLUGIN_ROOT}/skills/perfect/REFERENCE.md. The mission template lives in ${CLAUDE_PLUGIN_ROOT}/skills/perfect/PROMPT-TEMPLATE.md.

Target types available: plan, spec, report, vision, brief, north-star, strategy, proposal, manuscript, analysis, custom. See REFERENCE.md §6 for per-type structure expectations and recommended iteration depth.

When to Use

USE Crucible when:

• Leo provides a long brain-dump transcript or messy notes and asks for a structured document (plan, spec, report, vision, brief, north-star, strategy doc, etc.)
• Leo says "perfect this," "iterate this," "research and refine," "make this best-practice," "make this the best ever"
• Leo says "draft it with hypotheses and unknowns and loop on it"
• A document already exists but Leo wants it taken to a higher bar through research-driven refinement
• A document needs to be defensible to a client, partner, or audience and "draft once then ship" won't clear the bar
• Leo wants a single canonical artifact at the end, not a conversation or a set of decision options

Do NOT use Crucible when:

• Leo asks for a quick answer, a decision packet, or a conversation (use Jordan's normal mode)
• The need is code or implementation (Crucible is for documents, not code)
• Multiple branching options are needed (use a decision-packet pattern)
• The input is already polished and just needs a small edit (use Edit tool)
• Leo explicitly wants to ideate rather than land an artifact

How to Invoke

Slash invocation (preferred):

/crucible:perfect <target-type> <input-path-or-content> [--output <output-path>] [--max-iterations <n>] [--model <opus|sonnet>]

The skill is namespaced because it ships as a plugin. crucible comes from the plugin name; perfect is the skill name within the plugin. Standalone installations at ~/.claude/skills/crucible/SKILL.md use the unnamespaced /crucible invocation.

Natural-language invocation: When Leo says any of the trigger phrases above and provides raw input + a target, just run Crucible. Confirm the target type and output path with Leo once, then execute.

Required arguments:

• <target-type> — one of: plan, spec, report, vision, brief, north-star, strategy, proposal, manuscript, analysis, or custom (caller specifies in mission brief)
• <input> — either a file path (~/path/to/transcript.md) or inline content delimited by triple backticks

Optional arguments:

• --output <path> — output file path. Defaults to ~/forge-projects/crucible-output/<slug>-<YYYY-MM-DD>.md
• --max-iterations <n> — safety cap. Defaults to 10. Range: 3–20.
• --model <opus|sonnet> — subagent model. Defaults to opus for deeper iteration; specify sonnet for faster/cheaper runs.

Execution Flow

1. Parse and validate inputs.

   • Resolve input path or inline content. Reject if input is too short to need perfecting (< 200 words is probably not Crucible's job).
   • Resolve output path. Create parent directory if needed.
   • Validate target type. If custom, prompt Leo for a one-sentence description of the desired document.

2. Build the mission brief.

   • Read PROMPT-TEMPLATE.md.
   • Fill in: input content, target type, output path, completion-promise spec, max-iterations.
   • The mission brief is what gets fed to the subagent each iteration via ralph-wiggum's re-feeding.

3. Invoke ralph-wiggum.

   • Use the /ralph-loop command with:
     • The mission brief as the prompt
     • --completion-promise "PERFECTED" (subagent emits <promise>PERFECTED</promise> when conditions met)
     • --max-iterations from input
   • The Stop hook will re-feed until completion or cap.

4. The subagent does the work.

   • Crucible-Author runs the methodology each iteration (see REFERENCE.md for full detail).
   • Writes the working document to the output path; ralph sees the file persisting across iterations.

5. Collect and present.

   • When ralph loop terminates (PERFECTED or CAPPED), read the final document.
   • Surface to Leo: file path + summary + iteration count + whether it was PERFECTED or CAPPED.
   • If CAPPED, point Leo at the ## IMPERFECT — Unmet Conditions section explicitly.

Methodology Summary

The subagent's methodology, per iteration. Full details in REFERENCE.md.

Iteration 1 only — Hypothesis Pass:

• Read raw input in full
• Draft the full target document
• Tag every claim: [CONFIRMED], [HYPOTHESIS], [UNKNOWN], [CONCERN]
• Add ## Open Questions section enumerating every [UNKNOWN]
• Start ## Iteration Log

Iterations 2 through N:

• Research Pass — close [UNKNOWN] tags using WebSearch / WebFetch / file reads / MCP tools. Capture citations.
• Critique Pass — three naive Ralph-product-style questions on the doc as a whole.
• Refine Pass — tighten language, resolve contradictions, update Iteration Log.
• Stop Check — evaluate completion-promise conditions.

Completion Promise — when does Crucible stop?

Subagent emits <promise>PERFECTED</promise> ONLY when ALL are true:

1. Every claim carries an epistemic tag.
2. Every [CONFIRMED] claim has a citation OR an [internal] rationale.
3. No [UNKNOWN] tags remain. (Resolved unknowns escalated to Open Questions must be retagged inline as [DEFERRED → Open Q #N], not left as [UNKNOWN].)
4. Most recent Critique Pass produced zero new failure modes.
5. Prior iteration's Critique Pass also produced zero new failure modes (two consecutive clean passes).

Structural minimum: Because iteration 1 (Hypothesis Pass) runs no Critique Pass, condition 5 is unsatisfiable until iteration 3 at earliest. Documents requiring deep iteration (spec, strategy, proposal, analysis, manuscript per REFERENCE.md §6) realistically need iter 4-5 minimum before PERFECTED can fire.

If --max-iterations cap fires before completion, subagent finalizes with ## IMPERFECT — Unmet Conditions section and emits <promise>CAPPED</promise>.

Output

A single Markdown document at the specified output path. Structure:

# <Target Document Title>

## Summary
<one-paragraph summary of confirmed truths + remaining open questions>

## <Body sections per document type>
<claims tagged [CONFIRMED] (with citations), [HYPOTHESIS], [CONCERN]>

## Open Questions
<remaining items, if any, with rationale for why they could not be closed>

## Citations
<flat list of sources used, deduplicated>

## Iteration Log
- Iter 1 (Hypothesis Pass): <what was drafted, what tags emerged>
- Iter 2 (Research Pass): <what was researched, what tags resolved>
- Iter 3 (Critique Pass surfaces X, Refine resolves Y): ...
- ...
- Iter N: <PERFECTED or CAPPED>

Common Pitfalls

• Skipping the tagging. Untagged prose is the failure mode Leo is trying to escape. Every claim gets a tag, or the doc isn't done.
• Loop without research. Iterating on prose without doing actual research is theater. Each iteration must touch external sources OR resolve internal contradictions.
• Faking the completion promise. Subagent must not emit <promise>PERFECTED</promise> to escape the loop unless all five conditions are genuinely true. Ralph's own prompt template already enforces this; we reinforce it in PROMPT-TEMPLATE.md.
• Confirmation bias. Looking only for evidence that supports the draft. The Critique Pass is designed to find disconfirming evidence — don't soften it.
• Researcher-bias amplification. If first-pass research lands on flawed sources, subsequent iterations refine around them. Mitigate with source-diversity heuristics (see REFERENCE.md).
• Wrong skill for the job. If Leo wants options, use a decision-packet pattern. If Leo wants code, use the implementation lane. Crucible is for documents that need to be defensible.

Cost Note

A 10-iteration deep-doc loop with opus is non-trivial in token cost. Rough order: a 5,000-word document with 10 iterations against opus may consume 200k–500k tokens. Sonnet roughly halves that. Worth knowing before invoking on enormous inputs. Test with small inputs first.

Related Skills and Tools

• ralph-wiggum / ralph-loop — the loop engine Crucible depends on. Pre-installed.
• ralph-product — naive-challenge skill. Crucible's Critique Pass is inspired by this; consider invoking ralph-product directly for standalone challenge runs.
• autoresearch — adjacent prior-art plugin. Karpathy-inspired Modify→Verify pattern. Worth comparing on the same inputs.
• academic-research-skills — research→write→review→revise pipeline. Adjacent prior art.
• skill-creator — meta-tool used to scaffold this skill. Reference for SKILL.md structure.

Provenance

Built 2026-05-18 by Jordan + Claude per Leo's spec. FORGE packet: ~/kv-projects/FORGE/_forge/inbox/active/crucible-document-perfecter/

Drafted in response to Leo's verbal pattern, captured verbatim:

"When I provide a long brain dump transcript and request to build a document, plan, report, etc. this skill is used to draft, revise, research, perfect, via looping to a goal of the perfect, best practice, researched content EVER."