/craft-prompt

Craft Prompt

Generate a high-quality prompt for a frontier reasoning model. The prompt will give the model rich context and space to think — not prescribed conclusions.

Input: $ARGUMENTS

---

Critical Constraint: The Blind Model

The reasoning model you are crafting this prompt for has ZERO access to anything outside the prompt text. It cannot read files, access Linear, browse the web, or see conversation history. Everything it needs to reason well must be inlined in the prompt. If context is referenced but not included, the model will hallucinate or give generic advice.

This constraint drives every decision in this command.

---

Step 1: Understand Intent and Choose Mode

Start with the real question — not logistics.

From $ARGUMENTS, extract:

• The stuck point: What decision, direction, or problem does the user need an outside perspective on? This is the core of the prompt.
• Topic: What domain, system, or question is this about?
• Prior investigation: Has the user already explored this area? (Check for recent /investigate gap maps in ./compound-discoveries/*-gaps-*.md)
• Mode signal: Does context live in systems (assemble) or in the user's experience (interview)?

If the stuck point is unclear, ask ONE question before anything else:

"What would change if the reasoning model gave you a perfect answer? What decision would you make, or what direction would you take?"

Mode selection:

• If --review <project> flag is present → review mode
• If --interview flag is present → interview mode
• If the topic references specific systems, plugins, or codebases → assemble mode
• If the topic is organizational, strategic, or about the user's situation → interview mode
• If unclear → ask the user

Mode	Context Source	Best For
Assemble	Systems — files, APIs, web, investigation artifacts	Technical analysis, system comparison, post-investigation handoff
Interview	The user — via multi-round AskUserQuestion	Organizational design, strategy, personal workflows, domain expertise
Review	Compound-engineering knowledge base + git/Linear + short interview	Recurring project reviews — architecture critique, optimization proposals, test strategies

If $ARGUMENTS is empty or too vague to proceed, ask the user to describe what they want the reasoning model to help with.

---

Step 1b: Pull Investigation Artifacts

Before scoping, check if investigation work already exists.

1. Glob ./compound-discoveries/*-gaps-*.md — recent gap analysis artifacts
2. Glob ./compound-discoveries/*-reflection-*.md — recent reflection artifacts
3. Check if the user mentions coming from /investigate

If artifacts exist:

• Read the most recent gap map(s)
• Extract: user's stated intent, current state summary, ranked gaps, decisions made/pending
• This pre-fills much of the scoping — you already know what the user wants help with and what context matters
• Tell the user: "I found a gap analysis from {date} about {topic}. I'll use this as the foundation for the prompt's context. Anything to add or change?"

If no artifacts exist: Proceed to Step 2.

---

Step 2: Scope (both modes)

Ask 3-4 questions via AskUserQuestion. Lead with intent, not logistics. Use the prompt-craft skill's Phase 2 guidance.

Required decisions (get these answered, directly or via inference):

1. What the reasoning model needs to understand — "For the model to help with {stuck point}, it needs to understand {X}. What else is relevant?"
2. What you want back — A clear direction? A step-by-step plan? A critique? Trade-off analysis?
3. Target model — which reasoning model and single-shot vs. dialogue?
4. Scope boundaries — specific subsystems only, or system-wide? Any non-negotiable constraints?

If investigation artifacts were found in Step 1b, skip questions you can already answer from the gap map. Focus remaining questions on what the reasoning model should specifically help with.

Maximum 4 questions in this phase. Use the user's initial input + investigation artifacts to pre-fill what you can infer.

---

Step 2b: Interview (interview mode only)

When context lives in the user's head, run a multi-round interview before gathering any system context. Follow the prompt-craft skill's Phase 2b interview methodology.

Pre-Interview: Read Reference Documents

If the user references existing documents (Linear docs, files, specs), read them FIRST. They are the baseline — the interview surfaces how reality differs.

Interview Rounds

Run 3-5 rounds of 3-4 AskUserQuestion calls. Each round builds on the previous:

Round 1: Reality check — Team composition, current state, organizational maturity. Compare against any reference documents: "The doc says X — is that how it actually works?"

Round 2: How work flows — Actual intake, pain points, what's working vs. broken. Follow the user's energy — if they highlight a tension, dig into it.

Round 3: Structural tensions — Specific role boundaries, decision confusion, authority gaps. Reference what surfaced in Round 2.

Round 4: Context and constraints — Industry, authority level, success criteria, external references.

Round 5+ (if needed): Follow remaining threads until you can fully describe the user's reality to the reasoning model.

When to Stop

Stop interviewing when you can answer without guessing:

• What's the actual situation today?
• What are the 2-3 key tensions?
• What constraints exist?
• What does the user want to be different?

Capturing Interview Context

Throughout the interview, accumulate the user's answers — especially free-text notes where they speak in their own words. These become the context section of the prompt. The user's lived description of their reality is more valuable than any document.

---

Step 2c: Review Context Assembly (review mode only)

For recurring technical reviews of a project that uses compound-engineering.

2c.1: Load Static Profile (from compound-engineering knowledge base)

The profile IS the existing knowledge artifacts — no separate file needed:

1. Glob: subsystems_knowledge/**/*.yaml → read ALL specs
2. Read: subsystems_knowledge/architecture.yaml (if exists)
3. Read: ORCHESTRATOR.md (if exists)

Include the full subsystem specs in the prompt — not summaries. Trim only large ASCII diagrams from architecture.overview if needed for space.

2c.2: Check for Previous Reviews

Glob: scripts/reasoning-prompt-{project}-v*.md

If previous versions exist:

• Read the most recent version
• Extract the review date and any ## Review History section
• Note the commit hash or date for "since last review" dynamic context gathering
• The previous review's findings become context for this review

If no previous versions: this is v1, note it as the initial review.

2c.3: Gather Dynamic Context (automated)

Run these in parallel:

# Recent changes (since last review, or last 30 commits)
git log --oneline -30  # or git log --oneline --since={last_review_date}

# Change shape
git diff --stat {last_review_commit}..HEAD  # or just recent stats

# Current branch state
git status

Pull from Linear:

• Current milestone progress for the project
• Open issues, blockers, recently completed issues
• In-progress work

Optionally run tier0 tests from subsystem specs to capture current pass/fail state.

2c.4: Short Interview (1-2 rounds)

Unlike full interview mode, review interviews are short and focused on what's changed:

Round 1:

• "What's changed since we last looked at this? Any major architectural shifts?"
• "What's the current bottleneck or question?"
• "Any specific area you want challenged?" (architecture / optimization / testing / direction / open)

Round 2 (if needed): Follow up on the bottleneck — what have they tried, what's their current thinking.

2c.5: Assemble Versioned Prompt

Combine: review history + static profile + dynamic context + interview answers.

Write to scripts/reasoning-prompt-{project}-vN-{date}.md where N increments from the last version.

The prompt structure for reviews:

# Review: {project} — v{N}

## Your Role
[Open framing — set by interview focus or left broad]

## Review History
[Previous review findings and their status — compounds across versions]

## Architecture (Static Profile)
### Subsystem Map
[From subsystem specs — full specs inlined]
### Cross-Subsystem Invariants
[From architecture.yaml]
### Conventions, Decisions, Known Risks
[From ORCHESTRATOR.md]

## Current State (Dynamic)
### Recent Changes
[git log since last review]
### Milestone & Issues
[Linear state]
### Test State
[Current pass/fail if gathered]

## Current Focus
[From interview — what the user wants analyzed this review]

## Your Task
[Open-ended, shaped by interview focus but not prescriptive]

---

Step 3: Gather Context (assemble mode, or supplementary in interview/review mode)

Based on clarified intent, determine which context sources to pull from. Remember: the reasoning model is completely blind — everything must be inlined.

In interview mode, this step is optional — only gather from systems if the interview surfaces specific artifacts that should be included.

In review mode, static and dynamic context is already gathered in Step 2c. This step is only needed if the interview surfaces additional sources (e.g., "also look at how project X does it" or "check the Langfuse scores").

3a: Start from Investigation Artifacts

If Step 1b found investigation artifacts, use them as the foundation:

1. Gap map intent → becomes the Problem section's framing
2. Gap map current state → becomes part of the Context section
3. Ranked gaps → informs what the reasoning model should focus on
4. Decisions made → constraints the model must respect
5. Decisions pending → questions the model should help answer
6. Diagrams from investigation → translate to text descriptions for the prompt

Don't just reference these artifacts — distill them into the prompt. The reasoning model can't read files.

3b: Determine Additional Context Needs

Based on the stuck point + investigation artifacts + scoping answers, identify what's still missing:

What's Needed	Source	How to Gather
Project identity / product concept	Linear project description, README, PRODUCT.md	Linear MCP tools, Read
Subsystem architecture	subsystems_knowledge/**/*.yaml	Read full specs for relevant subsystems
Cross-subsystem constraints	architecture.yaml, ORCHESTRATOR.md	Read directly
Actual code (key interfaces, schemas)	Source files identified by starter_files or paths.owned	Read targeted excerpts — NOT entire files
Dependency context	Specs of subsystems that the focal subsystems depend on	Read at minimum: description, public_api, invariants
Project state	Linear milestones, open issues, blockers	Linear MCP tools
External references	Docs, blog posts, alternative approaches	WebSearch, WebFetch
Comparative systems	Other implementations of the same idea	Gather in parallel

3c: Gathering Principles

• Read source files directly — don't summarize from memory. The prompt needs accurate schemas, protocols, and decision tables.
• Gather comparatively — if user mentions multiple systems, gather all. Contrast enables reasoning.
• Gather what's working AND what's not — include the system's intended design alongside observed problems.
• Preserve specifics — include actual YAML schemas, actual protocol steps, actual flow diagrams. "The system uses a 5-phase protocol" is useless; the 5 phases with their gates and transitions are useful.
• Bridge abstraction levels — for focal subsystems, include BOTH the spec (architecture) AND key code (implementation). The model needs both to give advice that's sound and practical.
• Include dependency context — if the question is about subsystem A, and A depends on B and C, include enough about B and C (at minimum: description, public_api, invariants) that the model understands A's constraints.

3d: Delegation for Gathering

Use the Agent tool to parallelize independent research:

• One agent per external project to research
• One agent per plugin/system to deeply explore
• Keep the main thread for assembly

Each agent prompt should say: "This is a research task — return the raw content, don't summarize. I need accurate details for a reasoning model prompt. The reasoning model has NO access to the codebase — everything must be self-contained in the prompt."

---

Step 4: Assemble the Prompt

Follow the prompt-craft skill's Phase 4 structure:

4a. Role and Framing (2-3 sentences)

Set the reasoning model's perspective. Keep it open:

• "You are analyzing X" — not "You are an expert in X who believes Y"
• Include the user's vantage point if relevant: "The author of these systems wants to understand..."

4b. Context Section (~70-80% of prompt)

Organize by system/implementation, not by theme. For each:

1. What it is — one paragraph
2. How it works — the actual protocol, schema, flow (from gathered source files)
3. Key design decisions — what the designers chose (state neutrally)
4. What it has / doesn't have — capabilities AND limitations

If comparative: factual difference tables are context. Interpretive judgments are direction — omit them.

4c. Problem Section (~10-15%)

State what the user wants analyzed:

• Name the phenomenon or question
• Include observed symptoms if it's a diagnosis request
• Include ONE provocative open question to set the depth bar
• Do NOT name causes, solutions, or patterns

4d. Task Section (~10-15%)

Minimal output scaffolding:

• Name the parts at most ("Part 1: Principles. Part 2: Applications.")
• Do NOT prescribe what the model should find within each part
• Do NOT list example patterns, solutions, or frameworks
• End with: "Structure however serves the ideas best" or similar freedom signal

4e. Quality Check

Before writing the file, run two verification passes from the prompt-craft skill:

Pass 1: Self-Containment (The Blind Model Check)

Read the entire assembled prompt and ask: "If a brilliant developer who has never seen this project reads this, can they give specific, actionable advice?"

• Project identity: Does the prompt explain what this project IS?
• System boundaries: For every subsystem mentioned, is its purpose and scope clear?
• Dependency graph: Are component relationships explicit, not implied?
• Code grounding: Where the question touches implementation, is real code included?
• Constraints stated: Does the model know what CAN'T change?
• Intent included: Does the model know what the user wants to ACHIEVE?
• No dangling references: Does the prompt reference anything not included? (e.g., "see architecture.yaml" — the model CAN'T see it)

If any check fails, fix it before proceeding. A prompt that fails self-containment will produce generic advice.

Pass 2: Anti-Prescriptive Check

• Anti-prescriptive test: fewer than 2 named patterns/solutions in the task section
• Context accuracy: schemas and protocols match source files
• Ratio check: context is ~70-80% of total prompt
• Depth signal: at least one provocative open question
• Output guidance: minimal enough that a different structure would be fine

If any check fails, revise before writing.

---

Step 5: Write and Deliver

1. Write the prompt to scripts/reasoning-prompt-{slug}.md where {slug} is a kebab-case topic descriptor

2. Present a summary to the user:

   PROMPT CRAFTED
   ===
   File: scripts/reasoning-prompt-{slug}.md
   Target: {reasoning model}
   
   Context included:
   - {source 1}: {what was included}
   - {source 2}: {what was included}
   
   Problem framed as: {one-line summary of the problem section}
   Output type: {what the model is asked to produce}
   
   Prompt length: ~{word count} words
   Context/Task ratio: {percentage}
   

3. Ask if the user wants to adjust anything before using it.

---

Safety Rules

1. Never fabricate context. If a file doesn't exist or a system isn't well-documented, say so in the prompt rather than guessing.
2. Never prescribe conclusions. If you catch yourself writing "The key insight is..." or "The pattern here is..." in the task section, delete it.
3. Attribute context sources. Note which files, URLs, or tools provided each piece of context so the user can verify.
4. Respect prompt length. For single-shot prompts to models with smaller context windows, prioritize context quality over quantity. Cut the least relevant system, not the detail level.