Help us improve
Share bugs, ideas, or general feedback.
From beagle-analysis
Guides users through structured dialogue to turn fuzzy ideas into concrete, implementation-free project specs. Focuses on WHAT/WHY, never HOW.
npx claudepluginhub existential-birds/beagle --plugin beagle-analysisHow this skill is triggered — by the user, by Claude, or both
Slash command
/beagle-analysis:brainstorm-beagleThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn a fuzzy idea into a comprehensive, implementation-free project spec through collaborative dialogue.
Refines rough ideas into executable specifications via collaborative questioning, alternative exploration, and incremental validation. Invoke before creative work or implementation.
Guides collaborative brainstorming to refine ideas into approved designs and specs before any implementation of features, components, or changes. Enforces checklist and hard gates.
Turns fuzzy ideas into branching exploration trees via iterative divergence, deepening, and pruning; distills trees into specs with guided questions. Useful for ambiguous feature or workflow planning.
Share bugs, ideas, or general feedback.
Turn a fuzzy idea into a comprehensive, implementation-free project spec through collaborative dialogue.
The output is a standalone spec document — structured enough for any agentic system to consume, clear enough for a human to act on. It captures WHAT and WHY, never HOW.
<hard_gate> Do NOT write any code, create implementation plans, scaffold projects, or take any implementation action. This skill produces a SPEC DOCUMENT only. Every project goes through this process regardless of perceived simplicity — "simple" projects are where unexamined assumptions waste the most work. </hard_gate>
Complete these steps in order:
.beagle/concepts/<slug>/brief.md exists for this idea, ingest it and skip most of steps 2-4 (see Concept brief ingestion below)references/spec-reviewer.md).beagle/concepts/<slug>/spec.mdBrief present? ──→ Yes → Ingest brief (skip most discovery) ──┐
──→ No → Explore context → Assess scope │
├─ Too large? → Decompose → Brainstorm first sub-project
└─ Right size? → Clarifying questions ─┘
│
Both paths converge → Propose directions → Draft spec → Self-review (fix inline) → User review
├─ Changes? → Revise
└─ Approved? → Write to concept folder
The terminal state is a written spec. This skill does not transition to implementation, planning, or any other skill. The user decides what to do with the spec.
If the user invokes brainstorm-beagle on a concept that already has .beagle/concepts/<slug>/brief.md (produced by prfaq-beagle on pass), ingest the brief at step 1 and skip most discovery:
.beagle/concepts/<slug>/prfaq.md for the Reasoning blocks — they explain what was challenged and why earlier decisions were made. This is context, not content to re-litigate.The brief is a context handoff, not a gate. Run your own Self-Review on the spec you produce — brainstorm-beagle remains responsible for implementation-leakage detection, requirement testability, and scope discipline regardless of how much discovery was pre-done upstream.
When there is no brief: proceed through steps 2-9 normally. Not every idea comes from PRFAQ.
You are a thinking partner, not an interviewer. The user has a fuzzy idea — your job is to help them sharpen it.
How to question:
Question mechanics:
What to ask about:
| Ask about | Examples |
|---|---|
| Motivation | "What prompted this?" "What are you doing today that this replaces?" |
| Concreteness | "Walk me through using this" "Give me an example" |
| Clarification | "When you say X, do you mean A or B?" |
| Success | "How will you know this is working?" "What does done look like?" |
| Boundaries | "What is this explicitly NOT?" |
What NOT to ask about:
Background checklist (check mentally, not out loud):
When all four are clear, offer to proceed. If the user wants to keep exploring, keep going.
Before diving into questions, assess whether the idea is one project or several.
Signs it needs decomposition:
When decomposition is needed:
For right-sized projects, proceed directly to clarifying questions.
After understanding the idea, propose 2-3 high-level directions. These are product directions, not technical architectures.
Good directions:
Bad directions (implementation leaking in):
Lead with your recommendation and explain why. Present tradeoffs conversationally.
Brainstorming naturally generates ideas beyond the current scope. Handle this gracefully:
When the user expands scope mid-brainstorm:
"That's a great idea but it's its own project/phase. I'll capture it in Future Considerations so it's not lost. For now, let's focus on [current scope]."
The heuristic: Does this clarify what we're building, or does it add a new capability that could stand on its own?
Capture deferred ideas in the spec's "Future Considerations" section. Don't lose them, don't act on them.
The spec must never prescribe implementation. This is the hardest discipline.
| Allowed (WHAT) | Not allowed (HOW) |
|---|---|
| "Users can filter results by date and category" | "Add a /api/filter endpoint that accepts query params" |
| "Must support 10k concurrent users" | "Use Redis for session caching" |
| "Data must persist across sessions" | "Store in PostgreSQL with a users table" |
| "Must work offline" | "Use a service worker with IndexedDB" |
| "Search must feel instant" | "Use Elasticsearch with debounced queries" |
Exception — constraints: When the user has genuine constraints ("must use PostgreSQL because that's what our infra runs"), those go in the Constraints section with rationale. A constraint is a boundary condition, not a design choice made during brainstorming.
Some Key Decisions in a spec take the form "we will use feature X of tool Y to achieve Z" (e.g. "compile-time-checked SQL on both backends via sqlx's offline cache", "dual-platform builds via the framework's single-binary target"). These decisions look settled but encode an unverified assumption: that the tool actually behaves the way the docs imply when applied to this codebase.
When recording a Key Decision of this shape, do one of the following — never neither:
core/.sqlx/ with N existing query files is a citation; "sqlx supports compile-time checking" from memory is not.needs-spike-before-planning. Add an explicit marker to the Rationale: **Spike required:** before plan-lock, verify <specific command/behavior> against this repo and revise this decision if the result diverges from the assumption.A decision without either is a decision the downstream planner will encode as a fact and the executor will try to build against — and "the docs said it worked" is how a 5-line plan task balloons into a 400-line bash workaround. The spike tag tells the planner to add a Task 0 spike; the citation tells the planner the spike is already implicit in the existing code.
This rule is narrower than implementation leakage. The decision can still be at the WHAT level (e.g. "data must be type-checked at compile time" is WHAT). The rule applies only when the decision's rationale depends on specific tool behavior the user is asserting without evidence.
Use the template in references/spec-template.md. The spec has these sections:
Requirements must be concrete and testable:
| Good requirement | Bad requirement |
|---|---|
| "User can undo the last 10 actions" | "Good undo support" |
| "Page loads in under 2 seconds on 3G" | "Fast performance" |
| "Works with screen readers" | "Accessible" |
| "Export to CSV and JSON" | "Multiple export formats" |
After drafting the spec, review it for:
Fix issues inline. Then present to the user for review.
See references/spec-reviewer.md for the detailed review checklist.
Pass before presenting the draft (user review step): Advance only when every item is honestly yes — not “feels fine.”
references/spec-template.md (or you note deliberate omissions and why).references/spec-reviewer.md, except items explicitly listed under Constraints with rationale.Pass before creating or overwriting spec.md: Do not write until both are true.
.beagle/concepts/<slug>/spec.md, slug resolved (from brief frontmatter or agreed headline)..beagle/concepts/<slug>/spec.mdbrief.md frontmatter if a brief was ingested; otherwise derive a kebab-case slug from the concept headline (≤40 chars, no dates). User preferences override the default path.web-research or artifact-analysis mid-session, pass output_dir: /abs/path/.beagle/concepts/<slug>/research/ or /abs/path/.beagle/concepts/<slug>/analysis/ so findings share the concept folder with anything PRFAQ produced upstream. This keeps the whole concept-forging audit trail in one place.docs: add <slug> project spec"Spec written to
<path>. Review it and let me know if you want changes."