opencode-workflow/skills/analyze-architecture-for-code/SKILL.md

---
name: analyze-architecture-for-code
description: "Extract code-level requirements from the architecture document. Identify all components, data models, API contracts, service boundaries, and design decisions that must be translated into code-level design. The Code Design pipeline's first step. Produces internal analysis only — no file artifacts."
---

This skill extracts code-level requirements from the architecture document before designing code structure.

**Announce at start:** "I'm using the analyze-architecture-for-code skill to extract code-level requirements from the architecture document."

## Purpose

Read the architecture document and extract all components that must be translated into code-level design: services, repositories, models, API contracts, error model, consistency model, and async patterns. Identify the scope of code design work, flag ambiguities, and produce structured internal analysis that feeds into `design-code-structure`.

## Important

This skill produces **internal analysis only**. It MUST NOT write any file artifacts. The strict pipeline output is `docs/code-design/{feature}.md` only.

## Hard Gate

Do NOT start designing code structure in this skill. This skill only extracts and organizes architecture requirements for code-level translation. Design happens in `design-code-structure`.

## Process

You MUST complete these steps in order:

1. **Read the architecture document** at `docs/architecture/{date}-{feature}.md` end-to-end
2. **Inspect existing codebase** for current code structure, existing patterns, naming conventions, and technology stack (if applicable)
3. **Extract service boundaries** — List each service and its responsibilities, owned data, communication patterns
4. **Extract API contracts** — List each endpoint with method, path, request/response schemas, error codes
5. **Extract database schema** — List each table with columns, types, constraints, indexes, relationships
6. **Extract async flows** — List each async operation with trigger, queue, producer, consumer, retry policy
7. **Extract error model** — List error categories, propagation strategy, error response format
8. **Extract consistency model** — List idempotency requirements, transaction boundaries, saga patterns
9. **Extract security boundaries** — List auth mechanisms, authorization model, tenant isolation
10. **Extract integration boundaries** — List external systems with integration patterns, failure modes
11. **Extract observability requirements** — List logging, metrics, tracing, alerting requirements
12. **Identify existing codebase patterns** — If there is existing code, document current patterns for:
    - Directory structure
    - Package naming
    - Interface conventions
    - Error handling patterns
    - Testing patterns
    - DI approach
    - Config management
13. **Flag ambiguities** — Identify any architecture decisions that are unclear for code-level translation

## Analysis Format

Retain this analysis internally. Do not write it to a file.

```markdown
## Architecture Source
Reference to the architecture file being analyzed.

## Service Inventory
| Service | Responsibility | Owned Data | Communication | Code Packages Needed |
|---------|---------------|------------|---------------|---------------------|
| ... | ... | ... | sync/async | ... |

## API Endpoint Inventory
| Method | Path | Request Schema | Response Schema | Error Codes | Idempotent | Code Artifacts Needed |
|--------|------|---------------|-----------------|-------------|------------|----------------------|
| ... | ... | ... | ... | ... | Yes/No | handler, service method, DTO |

## Database Table Inventory
| Table | Columns (count) | Indexes | Relationships | Code Artifacts Needed |
|-------|----------------|---------|---------------|----------------------|
| ... | ... | ... | ... | migration, model struct, repository interface |

## Async Flow Inventory
| Operation | Trigger | Queue/Topic | Producer | Consumer | Code Artifacts Needed |
|-----------|---------|-------------|----------|----------|----------------------|
| ... | ... | ... | ... | ... | publisher, consumer handler, message struct |

## Error Model Summary
| Category | HTTP Status | Architecture Error Code | Go Error Type Needed |
|----------|-------------|------------------------|---------------------|
| ... | ... | ... | ... |

## Existing Codebase Patterns
| Pattern | Current Convention | Notes |
|---------|-------------------|-------|
| Directory structure | ... | ... |
| Package naming | ... | ... |
| Interface convention | ... | ... |
| Error handling | ... | ... |
| Testing pattern | ... | ... |
| DI approach | ... | ... |
| Config management | ... | ... |

## Code Design Scope Summary
Total interfaces needed: X
Total structs needed: X (domain: X, DB model: X, DTO: X)
Total migration files: X
Total error types: X

## Ambiguities And Gaps
List any architecture decisions that are unclear for code-level translation and need Architect clarification. If none, write "None identified."
```

## Primary Input

- `docs/architecture/{date}-{feature}.md` (required)

## Output

Internal analysis only. No file artifact. Findings are carried forward in memory to inform `design-code-structure`.

## Transition

After completing this internal analysis, proceed to `design-code-structure` with the architecture document and analysis findings in memory.

## Guardrails

This is a pure analysis skill.

Do:
- Extract all architecture components that need code-level translation
- Identify existing codebase patterns and conventions
- Count and catalog all interfaces, structs, and artifacts needed
- Flag ambiguities that block code design decisions

Do not:
- Design code structure
- Choose migration tools or DI frameworks
- Define interfaces or structs
- Write code
- Produce any file artifacts
- Write any file to disk