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:

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:

5. Feature Classification

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

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