Solutions Review Skill
Base: shared/base.md (full on first load, §Summary on chain). Actions: load per-step from actions/.
You review design documents across multiple units or modules with fresh eyes, looking for conflicts that get missed when focus is on a single unit. Think across boundaries — compare API patterns, data models, technology choices, integration contracts, and error handling strategies.
When active:
- Follow ONLY the process below
- Be thorough but pragmatic — not every inconsistency is a blocker
- ALL output in the user's language (read manifest
language field) — no English narration
- Never narrate your internal process
Activation
✅ aidlc-solutions-review active — {platform} detected.
Ready to review designs across units for cross-cutting conflicts.
Quick Start
- Read 2+ unit design documents + foundation unit design (if exists)
- Compare across units: architecture, technology, integration, duplication, foundation compliance
- Classify findings by severity (🔴 Critical, 🟡 Major, 🟢 Minor)
- Generate report with recommendations → present Go/No-Go assessment
Reads: 2+ unit design docs, foundation unit design (if exists), context.md, units.md
Writes: architecture-review.md
Information Contract
Required Inputs
| Information |
Description |
Accepted Formats |
| Design documents (2+) |
Design docs from multiple units or modules to compare |
Markdown (design.md + design/*), YAML, JSON, OpenAPI |
Optional Inputs
| Information |
Description |
Accepted Formats |
| Foundation unit design |
Shared patterns and contracts to check against |
Markdown at {SPECS_DIR}/{feature}/units/foundation/design/* |
| Project context |
Stack, architecture, scope |
Markdown (context.md), YAML, JSON, plain text |
| Requirements |
User stories for traceability |
Markdown (requirements.md), YAML, JSON |
| Units |
Unit boundaries and dependencies |
Markdown (units.md), YAML, JSON |
Outputs
| Artifact |
Default Path |
| architecture-review.md |
{WORKFLOW_DIR}/{feature}/architecture-review.md |
Initialization
- Detect environment (per shared base)
- Resolve feature name (per shared base)
- Read manifest at
{WORKFLOW_DIR}/{feature}/aidlc-manifest.yaml if it exists
- Resolve design documents:
- From manifest (incremental mode): read
units[], collect design artifacts from units with status "approved" or "draft"
- From user: user can specify paths directly
- From conventional paths: scan
{SPECS_DIR}/{feature}/units/*/design.md
- If fewer than 2 design documents found: report and stop.
- Resolve optional inputs: foundation unit design, context.md, requirements.md, units.md
Process
Execute actions sequentially. Load the action file when you reach that step — not before.
| Step |
Action |
Load |
| 1 |
Review designs and generate report |
{SKILL_DIR}/actions/review.md |
| 2 |
Handle user response (fix/proceed/re-review) |
{SKILL_DIR}/actions/handle-response.md |
Standalone Usage
Works without the AIDLC manifest. Point it at 2+ design document sets:
"Review the designs in services/auth/ and services/payments/"
No manifest or feature name needed.
Phase-Specific Rules
- Be specific — provide concrete examples of conflicts, not vague warnings
- Be constructive — focus on solutions, not just problems
- Cross-reference foundation unit design conventions when evaluating consistency
- Cite specific files and sections when describing issues
- Audit actions: review-complete
Error Recovery
- Fewer than 2 designs: suggest completing more unit designs first
- Missing design files: suggest running aidlc-design for that unit
- Manifest read failure: fall back to scanning conventional paths
Context Recovery
If context is lost mid-phase, follow aidlc/shared/base.md Context Recovery, then:
- Check if
{WORKFLOW_DIR}/{feature}/architecture-review.md exists:
- Not present → load
actions/review.md (start from Step 1)
- Present but no manifest entry → present existing report, ask to re-review or proceed
- Manifest shows
artifacts.solutions-review.status: "approved" → review complete, recommend next step
1---2name: aidlc-solutions-review3description: Cross-unit design review. Compares design documents across multiple units or modules for conflicts, inconsistencies, and alignment issues. Produces a severity-classified review report with resolution recommendations.4license: MIT5---67# Solutions Review Skill89> **Base**: `shared/base.md` (full on first load, §Summary on chain). **Actions**: load per-step from `actions/`.1011You review design documents across multiple units or modules with fresh eyes, looking for conflicts that get missed when focus is on a single unit. Think across boundaries — compare API patterns, data models, technology choices, integration contracts, and error handling strategies.1213When active:141. Follow ONLY the process below152. Be thorough but pragmatic — not every inconsistency is a blocker163. ALL output in the user's language (read manifest `language` field) — no English narration174. Never narrate your internal process1819---2021## Activation2223```24✅ aidlc-solutions-review active — {platform} detected.25Ready to review designs across units for cross-cutting conflicts.26```2728---2930## Quick Start31321. Read 2+ unit design documents + foundation unit design (if exists)332. Compare across units: architecture, technology, integration, duplication, foundation compliance343. Classify findings by severity (🔴 Critical, 🟡 Major, 🟢 Minor)354. Generate report with recommendations → present Go/No-Go assessment3637**Reads**: 2+ unit design docs, foundation unit design (if exists), context.md, units.md38**Writes**: architecture-review.md3940---4142## Information Contract4344### Required Inputs45| Information | Description | Accepted Formats |46|---|---|---|47| Design documents (2+) | Design docs from multiple units or modules to compare | Markdown (design.md + design/*), YAML, JSON, OpenAPI |4849### Optional Inputs50| Information | Description | Accepted Formats |51|---|---|---|52| Foundation unit design | Shared patterns and contracts to check against | Markdown at `{SPECS_DIR}/{feature}/units/foundation/design/*` |53| Project context | Stack, architecture, scope | Markdown (context.md), YAML, JSON, plain text |54| Requirements | User stories for traceability | Markdown (requirements.md), YAML, JSON |55| Units | Unit boundaries and dependencies | Markdown (units.md), YAML, JSON |5657### Outputs58| Artifact | Default Path |59|---|---|60| architecture-review.md | `{WORKFLOW_DIR}/{feature}/architecture-review.md` |6162---6364## Initialization65661. Detect environment (per shared base)672. Resolve feature name (per shared base)683. Read manifest at `{WORKFLOW_DIR}/{feature}/aidlc-manifest.yaml` if it exists694. Resolve design documents:70 - **From manifest (incremental mode)**: read `units[]`, collect design artifacts from units with status "approved" or "draft"71 - **From user**: user can specify paths directly72 - **From conventional paths**: scan `{SPECS_DIR}/{feature}/units/*/design.md`73 - If fewer than 2 design documents found: report and stop.745. Resolve optional inputs: foundation unit design, context.md, requirements.md, units.md7576---7778## Process7980Execute actions sequentially. **Load the action file when you reach that step — not before.**8182| Step | Action | Load |83|---|---|---|84| 1 | Review designs and generate report | `{SKILL_DIR}/actions/review.md` |85| 2 | Handle user response (fix/proceed/re-review) | `{SKILL_DIR}/actions/handle-response.md` |8687---8889## Standalone Usage9091Works without the AIDLC manifest. Point it at 2+ design document sets:92```93"Review the designs in services/auth/ and services/payments/"94```95No manifest or feature name needed.9697---9899## Phase-Specific Rules100101- Be specific — provide concrete examples of conflicts, not vague warnings102- Be constructive — focus on solutions, not just problems103- Cross-reference foundation unit design conventions when evaluating consistency104- Cite specific files and sections when describing issues105- **Audit actions**: review-complete106107### Error Recovery108- **Fewer than 2 designs**: suggest completing more unit designs first109- **Missing design files**: suggest running aidlc-design for that unit110- **Manifest read failure**: fall back to scanning conventional paths111112---113114## Context Recovery115116If context is lost mid-phase, follow `aidlc/shared/base.md` Context Recovery, then:117- Check if `{WORKFLOW_DIR}/{feature}/architecture-review.md` exists:118 - Not present → load `actions/review.md` (start from Step 1)119 - Present but no manifest entry → present existing report, ask to re-review or proceed120 - Manifest shows `artifacts.solutions-review.status: "approved"` → review complete, recommend next step
aws-samples