P1 spec research policy

Skill babyworm/rtl-agent-team/skills/p1-spec-research-policy

Internal reference: p1 spec research policy (agent-loaded; do not invoke).From its SKILL.md

Install

npx -y skills add babyworm/rtl-agent-team --skill p1-spec-research-policy

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

16.0 KB, as published. Nobody here has run it

Phase 1 Research Policy

Core Principles

AskUserQuestion-First: Resolve every ambiguity, design choice, or scope decision via AskUserQuestion BEFORE proceeding. Never assume — a wrong assumption cascades to all later phases.
Structured Interview (before spec parsing): Interview the user first — one question per message covering goal, scope, constraints, priority trade-offs, verification strategy, and dependencies (full interview protocol owned by the goal-clarifier agent). Record answers in docs/phase-1-research/design-intent.md; resolve ambiguous spec language with the user's stated intent, never agent assumptions.
Approach Comparison for Open Items: When the spec allows multiple implementation paths, present a per-OPEN comparison table (Approach | Pros | Cons | Area Est. | Latency Est. | Recommendation) and let the user select via AskUserQuestion. Record choice + rationale in open-requirements.json resolution_rationale.
Incremental Requirement Approval: Seek approval in stages — interface/IO → functional (per block) → performance → open items — so users correct misinterpretations before they propagate. Finalize iron-requirements.json only after all stages are approved.
Domain-Consult-First: Invoke domain-consult for algorithms, standards, coding tools, and HW trade-offs — never research in isolation. Experts provide knowledge; spec-analyst captures it as structured artifacts.
Propose, Do Not Decide: Present algorithm/tool candidates with trade-offs; the user makes final selections. Architecture-level decisions (pipeline, partitioning, memory hierarchy) belong to Phase 2 — Phase 1 surveys and recommends.
Exhaustive Tree Exploration: Spawn maximum parallel agents to explore every feasible solution path before committing. Skip ONLY if the user specifies exact algorithm + architecture (even then, explore at least 2 variants for validation).

Spec Refinement Criteria

AskUserQuestion MUST cover these areas (skip items already provided by user):

Target codec, profile, level (e.g., H.264 High Profile Level 4.1)
Target resolution and framerate (e.g., 1080p@60fps, 4K@30fps)
Encoder, decoder, or both
Interface protocol (AXI4, AXI4-Lite, APB, custom)
Clock frequency target and process node (ASIC vs FPGA)
Feature scope restrictions (e.g., "TQ only", "intra-only")
Priority trade-off preference (throughput vs area vs power vs quality)

3-Round Chief Review Protocol

Mandatory 3 rounds, coordinated by rtl-architect (domain-agnostic default). If a domain chief exists (e.g., vcodec-chief-standard-expert for video-codec domain), invoke both rtl-architect AND domain chief for domain-specific validation:

Round 1: Cross-block data flow completeness, dependencies, performance constraints, fixed-point constraints, cross-block issues, [AMBIGUITY]/[CONFLICT] status Save: reviews/phase-1-research/research-review-r1.md
Round 2: Convergence assessment. Rebuttal: spec-analyst accepts/rejects each Round 1 finding with rationale. Even if converged, proceed to Round 3 Save: reviews/phase-1-research/research-review-r2.md
Round 3: Mandatory final quality pass. Remaining gaps → escalate via AskUserQuestion Save: reviews/phase-1-research/research-review-r3.md

Review criteria per round:

Data flow: inputs/outputs defined at every block boundary
Dependencies: which block produces/consumes what data
Performance: throughput, latency, bandwidth as specific numbers
Fixed-point: bit widths, rounding modes per block
Cross-block issues: RDOQ↔Entropy dependency, ME↔MC pipeline, etc.
Ambiguities: all resolved or promoted to [ARCHITECTURE_DECISION]

User may override round count: "set iterations to N" → N rounds (minimum 1).

Iron/Open Requirement Taxonomy

Phase 1 produces TWO requirement files instead of a single requirements.json:

docs/phase-1-research/iron-requirements.json — settled functional (REQ-F-NNN) and performance (REQ-P-NNN) requirements, authority = 1, binding for ALL downstream phases.
docs/phase-1-research/open-requirements.json — research topics (OPEN-1-NNN) that Phase 2 must investigate and resolve into architecture decisions.

Per-item field schemas for both files are owned by the spec-analyst agent prompt. This policy owns only the classification and verification rules below.

Classification Rules

Functional/performance requirements with clear, measurable acceptance_criteria → iron
Architecture/implementation choices needing further investigation → open
Items with ambiguity score > 0.5 → CANNOT become iron until clarified
A requirement cannot become iron until its ambiguity score passes (reproducibility check)

Iron/Open Classification Verification

After iron/open files are produced, verify:

FAIL conditions (must fix before exit):

acceptance_criteria contains vague terms ("should support", "adequate", "sufficient")
open item missing evaluation_criteria
open item has candidates.length ≤ 1
iron item missing violation_policy

WARN conditions (log and proceed):

iron ratio < 30% (most items pushed to open — weakens Phase 1 value)
open item related_iron is empty
CONDITIONAL PASS ambiguity axis linked to an iron-classified REQ

Port Naming Conventions (io_definition.json)

Inputs: i_ prefix (e.g., i_data, i_valid) — NOT suffix _i
Outputs: o_ prefix (e.g., o_result, o_ready) — NOT suffix _o
Bidirectional: io_ prefix (e.g., io_sda)
Clocks: clk (single domain) or {domain}_clk (e.g., sys_clk) — NOT clk_i
Resets: rst_n (single domain) or {domain}_rst_n (e.g., sys_rst_n) — NOT rst_ni
Single clock domain defaults to sys_clk / sys_rst_n

Self-Verification Format

Save to reviews/phase-1-research/research-review.md:

# Phase 1 Review: Research Completeness
- Date: YYYY-MM-DD
- Reviewer: spec-analyst
- Upper Spec: specs/
- Verdict: PASS | FAIL

## Feature Coverage Checklist
| Spec Section | Requirement ID | Status |

## Findings
### [severity] Finding-N: ...

## Verdict
PASS | FAIL: [reason]

Spec Feature Completeness Audit (MANDATORY — Step 7.5c / team T12b-T12c)

The extractor MUST NOT grade its own completeness: an extraction blind spot also biases the self-counted denominator (5-of-10 modes self-reports 5/5). The completeness verdict comes from an independent census + mechanical diff:

Independent feature census (clean context): spawn spec-analyst in FEATURE CENSUS MODE. It reads ONLY original spec sources (specs/**, docs/phase-1-research/goal.md, domain knowledge files) and MUST NOT read iron-requirements.json, open-requirements.json, or any prior Phase 1 analysis. Enumerate EVERY spec-defined item — expand mode/format tables item-by-item (e.g., each intra prediction mode, encoding mode, color format, block size is one entry). Write docs/phase-1-research/spec-feature-inventory.json:
```
{ "features": [ { "feature_id": "FEAT-001", "name": "...", "kind": "mode|format|algorithm|capability|constraint",
                  "source": { "document": "...", "section": "..." } } ] }
```
Mechanical diff (different agent): spawn rtl-architect to map every FEAT-* to REQ/OPEN IDs in iron ∪ open requirements. Per-feature status:
- EXTRACTED — mapped to at least one REQ/OPEN id
- EXCLUDED_BY_SCOPE — user-approved exclusion, ADR reference recorded
- MISSING — no mapping and no approval
Gap escalation: any MISSING feature → MUST ask user via AskUserQuestion:
- "Spec defines N features; requirements cover M. Omitting K features may reduce [quality metric]. Approve omission?"
- Approved → status EXCLUDED_BY_SCOPE + ADR with rationale and impact estimate
- Not approved → add REQ-F-* to iron-requirements.json as MUST_IMPLEMENT, re-run diff

Documentation: save docs/phase-1-research/feature-coverage.md:

| Feature | Spec Source | REQ/OPEN IDs | Status |
|---------|-------------|--------------|--------|
| Intra mode DC | §8.3.1 | REQ-F-012 | EXTRACTED |
| Intra mode planar | §8.3.2 | — (ADR-007) | EXCLUDED_BY_SCOPE |

plus totals: features / extracted / excluded_by_scope / missing.

Gate: PASS iff missing == 0 (every feature EXTRACTED or EXCLUDED_BY_SCOPE). FAIL blocks Phase 1 completion (feature-coverage-audited completion criterion).
Downstream contract: spec-feature-inventory.json is the authoritative spec-item denominator for later phases; EXCLUDED_BY_SCOPE records let downstream gates distinguish user-approved scope reduction from silent extraction loss.
Reference model cross-check (Phase 2+, when refC or an external golden exists): compare the inventory against model implementation — "enum declared but function not implemented" → COVERAGE_GAP warning.

Escalation & Stop Conditions

Spec document not found → report to user, halt
Conflicting requirements between experts → flag conflict in domain-analysis.md, ask user
Chief not converged after 3 rounds → escalate remaining gaps to user with specific questions
Sub-domain expert returns [DOMAIN_UNCERTAINTY] → AskUserQuestion before proceeding

Ambiguity Score Protocol

Every Phase 1 completion MUST include an ambiguity assessment:

spec-analyst produces Ambiguity_Assessment with per-axis scores
Ambiguity Gate enforced by both orchestrators:
- p1-research-orchestrator: Step 7.5
- p1-research-team-orchestrator: Step 3.5
Score is recorded in docs/phase-1-research/ambiguity-assessment.md
Phase 2 entry reads this score — if > 0.3, phase 2 reviewers prioritize clarifying those axes

This is inspired by Ouroboros's AmbiguityScorer pattern:

Goal Ambiguity (40%): Is the design objective ambiguous? (0.0=clear, 1.0=ambiguous)
Constraint Ambiguity (30%): Are timing/area/power/protocol constraints missing? (0.0=explicit, 1.0=missing)
AC Ambiguity (30%): Are acceptance criteria untestable? (0.0=testable, 1.0=untestable)

Scoring: ambiguity_score = weighted_average(goal, constraint, ac) — higher = worse

≤ 0.3: PASS — proceed to Phase 2
0.3–0.5: CONDITIONAL PASS — log warnings, Phase 2 reviewers focus on flagged axes
> 0.5: BLOCK — resolve top ambiguities via AskUserQuestion before proceeding

Adversarial Interpretation Gate (Steps 7.6-7.9)

After ambiguity gate (Step 7.5a) and iron/open verification (Step 7.5b) pass, run adversarial reinterpretation to surface ambiguities the initial analysis missed.

Protocol (summary — Task-level orchestration owned by p1-research-orchestrator Steps 7.6-7.9)

7.6 Challenge: adversarial spec-analyst (clean context) challenges iron-requirements.json by source.section (not REQ ID); types: REINTERPRETATION (alternative reading) and OMISSION (zero-REQ spec feature vs spec-feature-inventory.json → original_interpretation="NOT_EXTRACTED", severity HIGH). Output .rat/scratch/stability/phase-1/challenge-report.json (schema: skills/p1-spec-research/templates/challenge-report-schema.json; max 30 per pass).
7.7 User resolution: HIGH individually via AskUserQuestion; MEDIUM batched if >10; LOW auto-documented. User may mark challenges NOT_GENUINE.
7.8 Re-run: spec-analyst re-analyzes with accumulated clarifications → all 4 canonical artifacts (iron/open requirements, io_definition, timing_constraints) + self-validation.
7.9 Gate check: compute Gate Metric below + save reviews/phase-1-research/stability-report.md.

Gate Metric

genuine = (HIGH + MEDIUM challenges) - NOT_GENUINE
resolved = RESOLVED + DOCUMENTED
resolution_ratio = resolved / genuine   (if genuine == 0: pass)
gate_pass = (all HIGH resolved) AND (resolution_ratio ≥ 0.8)

Gate failure: list unresolved HIGH challenges, loop back to Step 7.7 (max 1 re-loop). After 2nd failure: escalate to user with full divergence report.

Dual Gate Arbitration (Ambiguity Score + Adversarial Gate)

Ambiguity Score	Adversarial Gate	Decision
PASS (≤0.3)	PASS	Proceed
PASS (≤0.3)	FAIL	BLOCK
CONDITIONAL (0.3-0.5)	PASS	Proceed with WARNING
CONDITIONAL (0.3-0.5)	FAIL	BLOCK
BLOCK (>0.5)	PASS	BLOCK
BLOCK (>0.5)	FAIL	BLOCK

Rule: Either gate can block; neither can unblock the other.

Severity Classification

Severity	Criterion	Example
HIGH	Missing item (OMISSION)	Spec defines 10 encoding modes, only 5 extracted
HIGH	Different RTL behavior	Signed vs unsigned arithmetic
HIGH	Different interface	32-bit vs 64-bit datapath
MEDIUM	Different parameterization	Fixed depth vs configurable
MEDIUM	Different timing	3-stage vs 4-stage pipeline
LOW	Cosmetic only	Block naming differences

Boundary rule: alternative interpretation would cause different RTL module → HIGH. Same module but different parameters → MEDIUM. Same module, same parameters → LOW.

Pathological Patterns

Zero challenges on >15 requirements → re-run with stronger adversarial framing
50% items at HIGH severity → spec fundamentally under-specified, escalate
Challenge budget exceeded (>30) → rank by severity, return top 30