blueprint-discovery

Blueprint Discovery

Handles Steps 1-5 of the blueprint workflow: Idea Refinement, Research Decision Signals, Interview decision, Acceptance Criteria gathering, and Feature Classification.

Input

feature_description: string  # Raw feature description from user

1. Idea Refinement

Quick clarification before deep discovery. Catches misunderstandings early with 1-3 targeted questions.

Trigger when:

• feature_description < 100 characters
• Contains uncertainty: "maybe", "probably", "something like", "I think", "not sure"
• Missing core elements: no clear action verb OR no clear subject

Skip when:

• Description is detailed (> 200 characters with clear intent)
• User says "proceed" or "skip refinement"
• Bug fix with reproduction steps

If triggered:

AskUserQuestion:
  question: "Quick check - what's the primary goal?"
  header: "Goal"
  options:
    - label: "Add new capability"
      description: "Feature that doesn't exist yet"
    - label: "Fix broken behavior"
      description: "Something that should work but doesn't"
    - label: "Improve existing feature"
      description: "Enhancement to current functionality"
    - label: "Refactor/cleanup"
      description: "Better code without behavior change"

Follow-up (if answer reveals gaps):

If goal == "Add new capability":
  AskUserQuestion:
    question: "Who will use this and when?"
    header: "Context"
    options:
      - label: "End users in the app"
      - label: "Admins/internal team"
      - label: "Developers/API consumers"
      - label: "Automated systems"

If goal == "Fix broken behavior":
  AskUserQuestion:
    question: "How does it fail?"
    header: "Symptom"
    options:
      - label: "Error/crash"
      - label: "Wrong output"
      - label: "Missing data"
      - label: "Performance issue"

Max 3 questions total. After refinement:

refined_description = original + goal + context/symptom (if asked)

Output skip offer:

"Got it: {refined_description}. Ready to proceed, or clarify further?"

2. Research Decision Signals

During refinement, gather signals to inform the research decision in blueprint-research.

Infer from conversation:

Signal	How to Detect
user_familiarity	Points to existing code examples? Knows where files live? → high
user_intent	"Quick fix", "ship today" → speed / "want it right", "research first" → thoroughness
topic_risk	Keywords: auth, payment, stripe, security, encrypt, API key, webhook → high
uncertainty_level	"Not sure how", "what's the best way", exploring options → high

If signals unclear, quick probe:

AskUserQuestion:
  question: "What matters more for this task?"
  header: "Priority"
  options:
    - label: "Get it done fast"
      description: "Good enough solution, ship quickly"
    - label: "Get it done right"
      description: "Research best practices first"

Store signals for research phase.

3. Interview Decision

Suggest interview when:

• Feature description < 2 sentences
• Contains uncertainty words: "maybe", "probably", "something like", "not sure"
• Involves multiple stakeholders or systems
• User seems uncertain

Skip interview for:

• Bug fixes with clear reproduction steps
• Small, well-defined tasks (< 3 files likely)
• Features with existing specs/PRDs referenced

If interview suggested:

AskUserQuestion:
  question: "This feature could benefit from a requirements interview. Explore in depth first?"
  options:
    - "Yes, interview me first" → Invoke /interview with feature_description
    - "No, proceed to planning" → Continue

4. Acceptance Criteria

MANDATORY: Ask what "done" means.

AC describes feature behaviors only. Quality gates (tests, lint, review) handled by other agents.

AskUserQuestion:
  question: "What behavior must work for this feature to be done?"
  header: "Done when"
  multiSelect: true
  options:
    - label: "User can perform action"
      description: "Feature enables a specific user action"
    - label: "System responds correctly"
      description: "API/backend behaves as expected"
    - label: "UI displays properly"
      description: "Visual elements render correctly"
    - label: "Data is persisted"
      description: "Changes are saved to database"

Good AC examples:

• "Authenticated user can login and redirect to dashboard"
• "Form validates email format before submission"
• "API returns 404 for non-existent resources"

Bad AC examples (handled elsewhere):

• "Tests pass" → always-works-verifier
• "Code reviewed" → quality-gate
• "No lint errors" → slop-remover

Capture verification method for each criterion:

Criterion	Verification
User can login	curl -X POST /login or manual
Form validates	rspec spec/features/signup_spec.rb
API returns 404	curl /api/nonexistent

5. Feature Classification

Type	Detection Keywords	Action
UI	page, component, form, button, modal, design, view, template	Check design system
DevOps	terraform, ansible, infrastructure, cloud, docker, deploy, server	Delegate to devops-plan
API	endpoint, route, controller, request, response, REST, GraphQL	Standard flow
Data	migration, model, schema, database, query	Standard flow

UI Feature Flow:

1. Read config: config_read("design_system_path")
2. If empty, check: docs/design/design-system.md
3. If no design system: Suggest Skill("ux-brief") first

DevOps Feature Flow:

Skill(skill: "majestic-devops:devops-plan")

6. Repository Analysis (Onboarding Context)

When working on an unfamiliar codebase, gather structural context before feature planning.

Research Areas

Area	What to Check
Architecture	ARCHITECTURE.md, README.md, CONTRIBUTING.md, CLAUDE.md, AGENTS.md
Issue/PR patterns	.github/PULL_REQUEST_TEMPLATE*, .github/ISSUE_TEMPLATE/
Contribution guidelines	Coding standards, testing requirements, review processes
Codebase patterns	Naming conventions, module boundaries, implementation patterns

Structural Analysis Tools

• Use ast-grep via Bash for syntax-aware structural matching when text search is insufficient:

  ast-grep --pattern 'class $NAME < ApplicationRecord' --lang ruby
  

• Cross-reference discoveries across sources
• Prioritize official docs over inferred patterns
• Note inconsistencies or documentation gaps

Repository Analysis Output

## Repository Research Summary

### Architecture & Structure
- Project organization and tech stack
- Key architectural decisions

### Conventions
- Issue/PR formatting and labels
- Coding standards and testing requirements

### Implementation Patterns
- Common code patterns and naming conventions
- Project-specific practices

### Recommendations
- How to align with project conventions
- Areas needing clarification

Output

discovery_result:
  refined_description: string  # Original + refinement context
  refinement_skipped: boolean
  interview_conducted: boolean
  interview_output: string | null  # If interview was run
  acceptance_criteria:
    - criterion: string
      verification: string
  feature_type: "ui" | "devops" | "api" | "data" | "general"
  design_system_path: string | null  # For UI features
  # Research decision signals (for blueprint-research)
  user_familiarity: high | medium | low
  user_intent: speed | thoroughness
  topic_risk: high | medium | low
  uncertainty_level: high | medium | low
  ready_for_research: boolean