p1-spec-research

name	p1-spec-research
description	Phase 1 spec research: refines spec, fills gaps via user Q&A, surveys algorithm candidates with trade-offs. Use for 'research', 'spec analysis', 'Phase 1'.
user-invocable	true
argument-hint	[spec-file or project-description]
allowed-tools	Bash, Read, Write, Edit, Task, Grep, Glob, AskUserQuestion

Execute Phase 1 spec research pipeline. Refines specification, identifies gaps, surveys candidate algorithms with trade-offs, and produces structured research artifacts for Phase 2 architecture design.

<Use_When>

• Starting a new RTL design from a specification or idea
• Need thorough spec analysis before architecture design
• User says "research", "spec analysis", "Phase 1"
• Specification has ambiguities or missing information </Use_When>

<Do_Not_Use_When>

• Phase 1 artifacts already exist and are current
• Only need a quick domain question (use domain-consult)
• Need architecture design (use p2-arch-design — requires Phase 1 completion) </Do_Not_Use_When>

<Phase_Workflow> This skill runs as two stages inside the same Task() invocation:

• Phase 0 (goal-clarifier): when $ARGUMENTS is a sparse seed, the orchestrator first dispatches goal-clarifier for an ambiguity-scored interview across 4 RTL dimensions (Functionality / PPA Target / Scope / Verification). Phase 0 writes docs/phase-1-research/goal.md.
• Phase 1 (spec-analyst + research): spec-analyst consumes goal.md (plus any user-supplied spec document) and produces the iron/open requirements set as before.

When $ARGUMENTS points to an existing .md/.txt/.rst spec or is already a rich seed (≥ 500 chars with PPA/coverage signals), Phase 0 is skipped automatically. </Phase_Workflow>

| Path | Role | |------|------| | `scripts/score_ambiguity.py` | Pure stdlib helper for 4-dimension scoring + ambiguity %. Used by goal-clarifier each round. | | `templates/goal.md` | Output skeleton for `docs/phase-1-research/goal.md`. | | `references/goal-dimensions.md` | 4-dimension scoring rubric + question seeds + anti-patterns. |

Prerequisites

None — this is the first phase entry point.

Execution

Task(subagent_type="rtl-agent-team:p1-research-orchestrator", prompt="Execute Phase 1 spec research. User input: $ARGUMENTS")

Do not perform any work directly. The orchestrator agent manages spec refinement, solution tree exploration, sub-domain expert coordination, and 3-round chief review.

Output Artifacts

• docs/phase-1-research/iron-requirements.json — settled functional/performance requirements (REQ-F-, REQ-P-)
• docs/phase-1-research/open-requirements.json — research topics deferred to Phase 2 (OPEN-1-*)
• docs/phase-1-research/io_definition.json — I/O interface definitions
• Classification verification step confirms each requirement is tagged as either iron (acceptance_criteria defined) or open (research_needed).