# P1 Spec Research

> 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'.

- Skill: `babyworm/p1-spec-research` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add babyworm/p1-spec-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/babyworm/p1-spec-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: babyworm (https://skillmd.com/u/babyworm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/babyworm/p1-spec-research

---


<Purpose>
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.
</Purpose>

<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>

<Assets>
| 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. |
</Assets>

## 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).