| name | discover-docs |
| description | Use when bootstrapping or reviewing project documentation through concise Socratic discovery and targeted updates. |
Discover Docs
Usage
Invoke as fiddle:discover-docs [scope] — optional: vision, market, pricing, gtm, system, runbooks, or omit for full discovery.
Socratic dialogue to populate or review curated project docs. You question, challenge, and probe — then write the docs.
Docs schema
Each doc has a defined purpose, sections, and size constraint. Stay within them. The docs are for future-you and future-agents — concise, high-signal, no filler.
docs/product/VISION.md
Purpose: what this is, who it's for, why it exists.
Sections: What (1 paragraph), Who (1 paragraph), Success (2-5 concrete signals), Non-goals (bullet list), Open questions (bullet list).
Constraint: Under 1 page total. If longer, you're over-specifying.
docs/product/MARKET.md
Purpose: evolving understanding of the competitive landscape and users.
Sections: Landscape (1-2 paragraphs), Alternatives (short entry per competitor — name, what it does, strengths, weaknesses), Positioning (2-3 sentences), Users (what you know about actual/potential users), Research log (dated entries, append-only).
Constraint: Main sections should fit on one screen. Research log grows unbounded.
docs/product/PRICING.md
Purpose: how this makes money or why it doesn't.
Sections: Model (1 paragraph or options list), Costs (rough numbers), Comparable pricing (reference alternatives), Current state (what's live today), Research log.
Constraint: Half a page for main sections. Skip entirely for projects that will never monetize.
docs/product/GTM.md
Purpose: how people find and start using this.
Sections: Channels (where you promote), Messaging (one-sentence descriptions and hooks), Traction (dated log of notable events).
Constraint: Keep it short. Solo dev GTM is often one paragraph. That's fine.
docs/technical/SYSTEM.md
Purpose: how the system actually works today. Ground truth, not aspirational.
Sections: Overview (1 paragraph), Components (one entry per component — what, tech, where, dependencies), Data (flows, storage, key schemas), Infrastructure (where it runs), Invariants (must-be-true constraints), Known issues (specific, with file references where possible).
Constraint: 1-2 pages max. If longer, the system is complex enough to warrant splitting into sub-docs.
docs/technical/RUNBOOKS.md
Purpose: operational procedures for 2am-you.
Sections: Deploy (commands, not prose), Rollback (specific steps), Common issues (symptom → cause → fix).
Constraint: Skip entirely for libraries or tools that don't run as services.
Process
1. Assess current state
Read all docs in docs/. Also read:
- The codebase structure (ls, key config files, README)
- Any context the user provides (conversation dumps, notes)
.beans/ if present — open epics and features for project direction
Classify each doc as: empty (template only), populated (has content), or stale (Last reviewed date > 30 days or content contradicts codebase).
2. Determine scope
If the user provided a scope argument (e.g., market), focus only on that doc.
If no scope: work through docs in this order — VISION first (everything else depends on it), then SYSTEM (ground technical truth), then MARKET, PRICING, GTM, RUNBOOKS.
Skip docs the user says aren't relevant (e.g., PRICING for a free tool, RUNBOOKS for a library).
3. For each doc in scope — Socratic dialogue
Draw the content out through questions rather than asking the user to fill in sections — a section-by-section prompt is a form, and a form surfaces only what the user already knew to write down.
When uncertainty is about the available environment rather than the product, use an optional diagnostic, not a required questionnaire: “What can the available tools and context do to reduce this uncertainty?” Ask it only when repository evidence cannot answer first.
If the doc is empty:
- Start with an open question about the topic area. For VISION: "Tell me what you're building and why." For MARKET: "Who would use this instead of what?"
- Listen to the answer. Ask follow-up questions that probe assumptions, surface unstated constraints, and explore alternatives.
- After 3-5 exchanges, summarize what you've heard and propose content for each section.
- Ask the user to confirm or correct.
If the doc is populated:
- Read the content. Cross-reference with other docs and the codebase.
- Identify: gaps (sections that are thin or empty), staleness (content that doesn't match current reality), inconsistencies (VISION says X but SYSTEM shows Y), missing non-goals (scope creep signals).
- Present your findings as questions, not accusations. "VISION says this is for solo devs, but SYSTEM describes three microservices — is that complexity still justified?"
- For each issue, discuss and then propose an update.
If the user provides conversation dumps:
- Extract relevant information first, then use it as input to the dialogue. Don't just transcribe — synthesize and challenge. "From your conversations it looks like you considered X and Y but went with Y. Is that still the right call? The landscape may have shifted."
4. Write the docs
After each doc's dialogue is complete:
- Write the content following the schema constraints above.
- Preserve any existing research log entries — append, never delete.
- Set
Last reviewed: to today's date.
- Show the user the full doc content before writing.
- Write only after confirmation.
5. Cross-doc consistency check
After all scoped docs are written, do a final pass:
- Does VISION's "Who" align with MARKET's "Users"?
- Does VISION's "Non-goals" align with what SYSTEM actually does?
- Does PRICING's model make sense for MARKET's positioning?
- Does GTM's channels match where MARKET's users actually are?
- Flag any inconsistencies for discussion.
Rules
- Never write docs without the user's confirmation.
- Never bloat a section beyond its schema constraint.
- Never remove research log entries or feedback entries.
- Challenge assumptions — that's the point. Be direct, not sycophantic.
- If the user doesn't know something, capture it as an Open Question in VISION or a gap note in the relevant doc. Unknown is a valid state.
- If a doc isn't relevant to this project, skip it. Don't force structure.
