rat-auto-design-policy

Files (1)

• SKILL.md

SKILL.md (first lines)

# RTL Auto-Design Policy

## Core Principles

### Hierarchical Spec Compliance
Lower phases MUST NOT violate upper phase specifications:
  Spec → Architecture → μArch → RTL → Verification
Each phase strictly adheres to decisions made in all preceding phases.
Deletion, reduction, or modification of features for convenience is FORBIDDEN.
If a change is needed, control returns to the upper phase for approval.

### Design Priority Order
1. Functional Correctness (highest) — Every required feature works exactly
2. Interface Compliance — Ports, protocols, timing match Architecture
3. Timing/Performance — Throughput, latency targets met
4. Area/Power (lowest)

### Cascading Quality
Higher abstraction levels demand MORE iterative refinement because their quality
cascades to ALL downstream phases. A defect at the architecture level costs orders
of magnitude more to fix at RTL than if caught during architecture review.

Graduated iteration by abstraction level:
  Phase 1 (Research): 3 mandatory rounds (chief-coordinated)
  Phase 2 (Architecture): dynamic convergence review (min 2, max 5 rounds per p2-arch-design-policy) — memory, performance, ref model consistency
  Phase 3 (μArch): dynamic convergence review (min 2, max 5 rounds per rtl-p3-uarch-policy) — performance, interface, memory optimization
  Phase 4 (RTL): Wave-based lint+sim (implementation-level)
  Phase 5 (Verify): Sub-phase parallel (terminal verification)

Iteration count can be increased beyond 3 if convergence is not achieved.
Principle: **refine thoroughly at the top, execute efficiently at the bottom.**

### Document-as-Memory
Design artifacts (docs/, reviews/) serve as persistent memory across phases and agents.
Each phase reads upstream documents as input context and writes downstream documents as output.
No agent needs to "remember" another agent's output — it reads the document.

Document flow:
  iron-requirements.json + open-requirements.json → arch-designer reads → architecture.md → uarch-designer reads →
  docs/phase-3-uarch/*.md → rtl-coder reads
  reviews/phase-N/ → Quality Gate reads → next phase proceeds or fails

State is persisted at `.rat/state/rat-auto-design-state.json` for resumability.

## Execution Rules

### Dual-Layer Phase Gates
Every phase transition requires BOTH:
1. **Artifact Gate**: Required files/directories exist (fast check)
2. **Quality Gate**: Reviewer agent(s) verify quality AND hierarchical spec compliance

Quality Gate verdicts: `PASS` or `FAIL + findings[]`

### Gate Retry Policy
- On Artifact Gate failure: retry the failed phase once, then escalate to user
- On Quality Gate failure: pass findings back to the phase's worker agent for correction,
  then re-run Quality Gate. Maximum 2 retry cycles per gate
- On upper-spec violation: IMMEDIATE STOP (see Escalation)

### Escalation Ladder (Per-Gate 2x)
Every active gate uses a per-gate retry budget `N` (`retry_limit` in state):
- **Primary range**: attempts `1..N` with normal strategy
- **Fallback range**: attempts `N+1..2N` with immediate strategy switch
  - split by module/requirement
  - swap reviewer+solver agent pairing
  - re-run only impacted checks
- **Last chance**: one automatic alternative attempt after `2N`
- **Post 2x+1 fail**: set `needs_user_decision=true` and stop for user direction

State contract for hook enforcement lives in:
- `orchestration_control.active_gate_*` (fast path for hooks)
- `orchestration_control.gates.{gate_id}` (per-gate detailed counters)

### Dynamic Prompt Injection
When entering fallback or last-chance stages, orchestrator writes:
- `orchestration_control.dynamic_prompt_text` (plain text, single-shot guidance)
- `orchestration_control.dynamic_prompt` metadata (`source`, `strategy_tag`, `used`)

Fallback templates are available in:
- `${CLAUDE_PLUGIN_ROOT}/skills/rat-auto-design/templates/escalation-prompts.json` (plugin runtime)
- `skills/rat-auto-design/templates/escalation-prompts.json` (development repo context)

Use templates only when LLM-generated prompt text is unavailable.
If both paths are unreadable, orchestrator MUST use the built-in defaults below and still
write the chosen text into `orchestration_control.dynamic_prompt_text` with
`orchestration_control.dynamic_prompt.source = "builtin"`:
- `primary`: Continue current gate workflow, focus on pending criteria with existing agent assignment.
- `fallback`: Split failing scope by module/requirement, switch reviewer+solver pairing, rerun impacted checks only.
- `last_chance`: Apply one non-overlapping alternative strategy, record deltas, prepare escalation context.
- `user_escalation`: Retries exhausted; ask user with failure summary, attempted strategies, and recommended options.

### Context Preload
Before each phase, verify required upstream files exist:
- **required (full read)**: files that MUST be fully read before starting the phase
- **summary only**: files where only the phase summary is sufficient
- **optional (on demand)**: files read only when a specific question arises

Agents entering a phase MUST load required files first, then summaries.
Specific file lists are defined inline in each orchestrator's phase steps.

### Scratchpad Convention
During iterative review rounds, reviewers write findings to:
  `.rat/scratch/phase-{N}/round-{R}-{agent}.md`

Coordinator reads all round files to aggregate:
  `.rat/scratch/phase-{N}/round-{R}-feedback.md`

On phase gate PASS: consolidated review saved to `reviews/phase-{N}-*/`, scratch cleaned.
On phase gate FAIL + retry: scratch files preserved for next round.

## Phase Gate Definitions

Every transition = Artifact Gate + Quality Gate (see Dual-Layer Phase Gates).
Quality-gate semantics — reviewer rosters, review rounds, rebuttal protocol, convergence,
and detailed pass/fail criteria — are OWNED by the per-phase policies in the table below.
This policy defines only the artifact/verdict contract the orchestrator checks.

| Gate | Artifact Gate (must exist) | Verdict File(s) | Verdict | Quality Gate |
|------|---------------------------|-----------------|---------|--------------|

From babyworm/rtl-agent-team, MIT.

More from babyworm/rtl-agent-team