Design Review

Structured adversarial review workflow for producing architectural designs, migration plans, RFCs, and technical proposals. Two simulated expert perspectives iterate on a design while a human reviewer provides constraints and direction at each round.

When to Use
Inputs
Workflow
Workflow Diagram
The Agents
Round Structure
Starting from a Topic
Starting from an Existing Document
Human Reviewer Interaction
Convergence Criteria
Document Output
Task Tracking
Troubleshooting
Related Skills

When to Use

Designing a new system architecture or migration plan
Writing an RFC or technical proposal that needs rigorous critique
Refining an existing design document through structured adversarial review
Any design task where multiple perspectives (implementer vs. quality advocate) improve outcomes

Inputs

The skill accepts one of two starting points plus optional configuration:

Input	Description	Example
Topic	A research question or design challenge	`"Migrate installer from Ansible to Kubernetes Operator"`
Existing document	File path to iterate on	`docs/architecture/migration-plan.md`
Max iterations	Number of review rounds (default: 5)	`--rounds 3`
Role context	Domain expertise for the agents	`"Senior Cloud Native Architect"`
Focus areas	Specific concerns to emphasize	`"RBAC security, OpenShift compatibility"`

Invocation examples:

/design:review Migrate the Rossoctl installer from Ansible/Helm to a Kubernetes Operator
/design:review docs/architecture/operator-migration.md
/design:review --rounds 3 Design an authentication gateway for multi-tenant agents
/design:review docs/rfc/007-observability.md --rounds 7 --focus "Day-2 operations, cost"

Workflow

1. Parse input → Topic or Existing Document
2. If topic: Research phase (codebase exploration, web search)
3. Lead Architect produces initial proposal (V1)
4. Quality Advocate critiques V1
5. Ask Human Reviewer for constraints or "proceed"
6. Lead Architect revises → V(N+1)
7. Quality Advocate critiques V(N+1)
8. Ask Human Reviewer again
9. Repeat 5-8 until:
   a. Quality Advocate has zero critical issues, OR
   b. Max iterations reached, OR
   c. Human Reviewer says "finalize"
10. Present final version + offer document export

Workflow Diagram

flowchart TD
    START(["/design:review"]) --> INPUT{"Input type?"}
    INPUT -->|Topic string| RESEARCH["Research Phase<br>Explore codebase + web"]:::design
    INPUT -->|Existing document| READDOC["Read & Analyze<br>Existing Document"]:::design

    RESEARCH --> V1["Lead Architect<br>Initial Proposal (V1)"]:::design
    READDOC --> V1

    V1 --> CRITIQUE["Quality Advocate<br>Critique"]:::review
    CRITIQUE --> HUMAN{"Human Reviewer<br>Constraints?"}:::human

    HUMAN -->|Additional constraints| REVISE["Lead Architect<br>Revise → V(N+1)"]:::design
    HUMAN -->|Proceed| REVISE
    HUMAN -->|Finalize| CONVERGE

    REVISE --> RECRITIQUE["Quality Advocate<br>Re-critique"]:::review
    RECRITIQUE --> CHECK{"Converged?"}

    CHECK -->|Zero critical issues| CONVERGE["Final Version"]:::done
    CHECK -->|Max rounds reached| CONVERGE
    CHECK -->|Issues remain| HUMAN

    CONVERGE --> EXPORT{"Export format?"}
    EXPORT -->|DOCX| DOCX["Generate .docx<br>python-docx"]:::output
    EXPORT -->|Markdown| MD["Write .md file"]:::output
    EXPORT -->|None| DONE(["Done"])

    DOCX --> DONE
    MD --> DONE

    classDef design fill:#1A5C8A,stroke:#333,color:white
    classDef review fill:#FF5722,stroke:#333,color:white
    classDef human fill:#4CAF50,stroke:#333,color:white
    classDef done fill:#795548,stroke:#333,color:white
    classDef output fill:#607D8B,stroke:#333,color:white

Follow this diagram as the workflow.

The Agents

Two simulated expert perspectives critique each other's work:

Lead Architect (Proposer)

Role: Proposes the design, CRD schemas, reconciliation logic, implementation strategy
Perspective: Implementer — focuses on feasibility, developer experience, clean architecture
Output: Versioned proposals (V1, V2, V3...) with concrete schemas, code samples, and diagrams
Adapts to: Human reviewer constraints and Quality Advocate critiques

Quality Advocate (Reviewer)

Role: Critiques the proposal for operational failures, security gaps, complexity bloat
Perspective: Adversarial — focuses on Day-2 operations, edge cases, blast radius, upgrade paths
Output: Bulleted critique organized by severity (Critical > Major > Minor)
Severity definitions:
- Critical: Must fix before proceeding. Architecture won't work as designed.
- Major: Significant risk. Could work but likely causes production incidents.
- Minor: Improvement opportunity. Non-blocking but worth addressing.

Adapting Agent Roles

The default roles (Architect + Quality Advocate) work for infrastructure/platform design. For other domains, adapt the perspectives to the problem:

Domain	Proposer Role	Reviewer Role
Infrastructure	Cloud Native Architect	SRE / Security Auditor
API Design	API Designer	API Consumer / DX Advocate
Data Architecture	Data Engineer	Data Governance / Privacy
Security	Security Architect	Red Team / Penetration Tester
UX/Product	Product Designer	Accessibility / Performance Advocate

State the adapted roles explicitly at the start of Round 1 so the human reviewer knows the perspectives being applied.

Round Structure

Each round follows this exact format:

Lead Architect Section

## Lead Architect: [Initial Proposal | Revised Plan] (V<N>)

[If V1: Present the full proposal with sections, schemas, code samples, diagrams]
[If V2+: Address each critique from the previous round, then present revised sections]

### [Section 1 Title]
[Content with code blocks, tables, diagrams as needed]

### [Section 2 Title]
...

Quality Advocate Section

## Quality Advocate: Critique of V<N>

### Critical Issues
- **[Issue title].** [Detailed explanation of why this is critical and what breaks.]

### Major Concerns
- **[Concern title].** [Explanation and suggested mitigation.]

### Minor Issues
- **[Issue title].** [Brief note.]

Human Handoff

Every round ends with exactly this prompt:

**Human Reviewer:** Do you have additional constraints or should we proceed to the next internal review?

Wait for the human response before continuing.

Starting from a Topic

When invoked with a topic string (no existing document):

Step 1: Research Phase

Before the Lead Architect writes V1, conduct research:

Codebase exploration — Use the Explore agent to understand relevant code, existing patterns, and architecture
Web research (if needed) — Search for best practices, prior art, and industry patterns relevant to the topic
Synthesize findings — Compile research into context for the Lead Architect

The research phase should be thorough but time-boxed. Use subagents for codebase exploration to keep the main context clean.

Step 2: Initial Proposal

The Lead Architect writes V1 grounded in the research findings. V1 should be comprehensive:

Problem statement and motivation
Proposed architecture with diagrams
Concrete schemas / interfaces / API surfaces
Implementation strategy with phases
Known trade-offs and alternatives considered

Starting from an Existing Document

When invoked with a file path:

Step 1: Read and Analyze

Read the existing document in full. Understand:

What decisions have already been made
What's well-defined vs. underspecified
What assumptions are stated vs. implicit

Step 2: Quality Advocate First

Skip the Lead Architect's V1 — the existing document IS V1. Start directly with the Quality Advocate's critique of the document.

Step 3: Normal Iteration

Continue with the standard round structure (Lead Architect revises, Quality Advocate re-critiques, human weighs in).

Human Reviewer Interaction

The human reviewer has several options at each handoff:

Response	Effect
Additional constraints	Lead Architect incorporates them into the next revision. State constraints explicitly at the top of the next Lead Architect section.
"proceed" / "continue"	Move to next round with no additional constraints.
"finalize"	Skip remaining rounds. Move directly to convergence and document export.
Change iteration count	e.g., "proceed, but let's do 3 more rounds" — adjust max rounds.
Change focus	e.g., "focus the next round on security only" — narrow the Quality Advocate's lens.
Change roles	e.g., "add a cost perspective" — adjust the adversarial lens.

Convergence Criteria

The review loop ends when ANY of these conditions are met:

Quality Advocate reports zero Critical and zero Major issues — the design has converged
Max iterations reached (default: 5) — present the best version achieved
Human Reviewer says "finalize" — explicit early termination

When converged, present:

## Consolidated Decision Record

| Decision | Rationale | Round |
|----------|-----------|-------|
| [Decision 1] | [Why] | R<N> |
| [Decision 2] | [Why] | R<N> |
...

Then offer document export.

Document Output

After convergence, offer the human reviewer export options:

The design has converged after N rounds. Would you like to export it?
1. **DOCX** — Generate a formatted Word document using python-docx
2. **Markdown** — Write to a .md file in the repo
3. **Both**
4. **None** — Keep it in the conversation only

DOCX Generation

When DOCX is selected, generate a python-docx script that produces the document:

Create a Python script at the target location (e.g., docs/architecture/generate-<topic>.py)
The script uses python-docx to create a professionally formatted document with:
- Title page with document metadata (version, date, status, authors)
- Table of contents
- All sections from the final version with proper heading hierarchy
- Formatted tables (colored headers, alternating row shading)
- Code blocks in monospace font
- Decision record table
Run the script to produce the .docx file
Report the output path and file size

Install python-docx if needed:

pip3 show python-docx 2>/dev/null || pip3 install python-docx

Markdown Generation

Write the final version as a clean markdown file with all sections, code blocks, tables, and the decision record. Use standard GitHub-flavored markdown.

Task Tracking

On invocation:

TaskList — check existing tasks for this design review
TaskCreate with naming: <repo> | <topic> | design:review | Round <N> | <description>

Example tasks:

rossoctl | operator-migration | design:review | Research | Explore codebase and current installer
rossoctl | operator-migration | design:review | Round 1  | Initial proposal + critique
rossoctl | operator-migration | design:review | Round 2  | Revise for RBAC + security
rossoctl | operator-migration | design:review | Round 3  | Address productization constraints
rossoctl | operator-migration | design:review | Export   | Generate DOCX document

Update task status as each round completes. Create new tasks when the human reviewer adds constraints that require research.

Troubleshooting

Problem: Rounds aren't converging

Symptom: Quality Advocate keeps finding new Critical issues at round 4-5. Fix: Ask the human reviewer to narrow focus ("focus only on RBAC for this round"). Broad scope prevents convergence. Alternatively, increase max rounds.

Problem: Lead Architect not addressing critiques

Symptom: Same Critical issue appears in multiple rounds. Fix: The Lead Architect MUST explicitly address every Critical and Major issue from the previous round. If an issue is intentionally deferred, state why with a "Decision: Accept Risk" note.

Problem: Design is too abstract

Symptom: Quality Advocate can't critique effectively because there are no concrete schemas or code. Fix: The Lead Architect MUST include concrete artifacts: CRD YAML, Go interfaces, sequence diagrams, RBAC manifests. Abstract bullet points are not sufficient for review.

Problem: python-docx not available

Symptom: DOCX generation fails. Fix: Install with pip3 install python-docx. If pip is not available, fall back to Markdown export.

Related Skills

meta:write-docs - Documentation formatting guidelines
skills:write - Create or edit skills
git:commit - Commit the generated design document
repo:pr - Create a PR for the design document
repo:issue - Create a tracking issue for the design

design:review

Files1

SKILL.md.claude/skills/design:review/SKILL.md