---
name: GudaSpec Research
description: Transform user requirements into constraint sets through parallel exploration and analysis
category: GudaSpec
tags: [gudaspec, research, constraints, exploration, subagents]
---

<!-- GUDASPEC:RESEARCH:START -->
**Core Philosophy**
- Research produces **constraint sets**, not information dumps. Each constraint narrows the solution space.
- Constraints tell subsequent stages "don't consider this direction," enabling mechanical execution without decisions.
- The output is "約束集合 + 可验证的成功判据" (constraint sets + verifiable success criteria).
- Eliminate ambiguity through structured exploration and user interaction.
- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**.

**Guardrails**
- **NEVER** divide subagent tasks by roles (e.g., "架构师agent", "安全专家agent"). 
- **ALWAYS** divide by context boundaries (e.g., "user-related code", "authentication logic", "infrastructure config").
- Each subagent context must be self-contained with independent output.
- **MANDATORY**: Use `mcp__auggie-mcp__codebase-retrieval` to minimize search/grep/find operations.
- All subagents must follow the same structured output template for aggregation.
- Do not make architectural decisions—surface constraints that guide decisions.

**Steps**
0. **Generate OpenSpec Proposal**
   - Run `/openspec:proposal`

1. **Initial Codebase Assessment**
   - Combine user requirements with quick codebase scan using `mcp__auggie-mcp__codebase-retrieval`.
   - Determine project scale: single directory vs. multi-directory structure.
   - **Decision point**: If code spans multiple subdirectories or modules → enable parallel Explore subagents.
   - Document finding: "Single agent serial exploration is inefficient; parallel subagents required."

2. **Define Exploration Boundaries (Context-Based Division)**
   - Identify natural context boundaries in the codebase (NOT functional roles).
   - Example divisions:
     * Subagent 1: User domain code (user models, user services, user UI)
     * Subagent 2: Authentication & authorization code (auth middleware, session, tokens)
     * Subagent 3: Configuration & infrastructure (configs, deployments, build scripts)
   - Each boundary should be self-contained: no cross-communication needed between subagents.
   - Define exploration scope and expected output for each subagent.

3. **Prepare Standardized Output Template**
   - Define a unified JSON schema that all Explore subagents must follow:
   ```json
   {
     "module_name": "string - context boundary explored",
     "existing_structures": ["list of key structures/patterns found"],
     "existing_conventions": ["list of conventions/standards in use"],
     "constraints_discovered": ["list of hard constraints that limit solution space"],
     "open_questions": ["list of ambiguities requiring user input"],
     "dependencies": ["list of dependencies on other modules/systems"],
     "risks": ["list of potential risks or blockers"],
     "success_criteria_hints": ["observable behaviors that indicate success"]
   }
   ```
   - Communicate template to all subagents for consistency.

4. **Parallel Subagent Dispatch**
   - For each defined context boundary, spawn an Explore subagent with:
     * **Explicit instruction**: "You MUST use `mcp__auggie-mcp__codebase-retrieval` to reduce search operations."
     * Defined scope and context boundary.
     * Required output template (from Step 3).
     * Clear success criteria: complete analysis of assigned boundary.
   - Monitor subagent execution and collect structured reports.

5. **Aggregate and Synthesize Reports**
   - Collect all subagent JSON outputs.
   - Merge findings into unified constraint sets:
     * **Hard constraints**: Technical limitations, existing patterns that cannot be violated.
     * **Soft constraints**: Conventions, preferences, style guides.
     * **Dependencies**: Cross-module relationships that affect implementation order.
     * **Risks**: Potential blockers that need mitigation.
   - Identify **open questions** from all reports that require user clarification.
   - Synthesize **success criteria** from scenario hints across all contexts.

6. **User Interaction for Ambiguity Resolution**
   - Compile prioritized list of open questions from aggregated reports.
   - Use `AskUserQuestions` tool to present questions systematically:
     * Group related questions together.
     * Provide context for each question.
     * Suggest default answers when applicable.
   - Capture user responses as additional constraints.
   - Update constraint sets with confirmed decisions.

7. **Generate OpenSpec Proposal**
   - Run `/openspec:proposal <requirement-description>` to scaffold formal spec.
   - Transform finalized constraint sets into requirements format.
   - Structure as:
     * **Context**: User need + discovered constraints
     * **Requirements**: Each constraint becomes a requirement with scenario
     * **Success Criteria**: Derived from aggregated hints and user confirmations
   - Ensure proposal includes:
     * All discovered constraints as requirements.
     * Verifiable scenarios for each requirement.
     * Clear dependencies and sequencing.
     * Risk mitigation strategies.

**Reference**
- Review existing constraints: `rg -n "Constraint:|MUST|MUST NOT" openspec/specs`
- Inspect codebase structure: `ls -R` or `mcp__auggie-mcp__codebase-retrieval`
- Check prior research outputs: `ls openspec/changes/*/research-output.md`
- Validate subagent outputs conform to template before aggregation.
- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.

<!-- GUDASPEC:RESEARCH:END -->