opencode-workflow/skills/challenge-architecture/SKILL.md

name	description
challenge-architecture	Silent audit and batch review of architecture decisions. Validates traceability, scalability, consistency, security, integration, observability, and detects over/under-engineering. Updates the single architecture file in place.

Perform a silent, structured audit of the architecture document against the PRD. Produce a single batch review with fixed output groups. Apply all fixes directly to the architecture file. Do not ask interactive questions.

Announce at start: "I'm using the challenge-architecture skill to audit and review the architecture."

Primary Input

• docs/architecture/{feature}.md
• docs/prd/{feature}.md

Primary Output (STRICT PATH)

• Updated docs/architecture/{feature}.md

This is the only file artifact in the Architect pipeline. Review findings and fixes are applied directly to this file. No intermediate files are written.

Audit Mode

This skill operates in silent audit / batch review mode:

• Read the architecture document and PRD in full
• Perform all validation phases silently
• Produce a single structured review with all findings grouped into fixed categories
• Apply all fixes directly to the architecture document
• Do NOT ask questions one at a time or interactively prompt the user

Audit Phases

Perform the following validations silently, collecting all findings before producing the review.

Phase 1: Traceability

For every architectural element, verify it traces back to at least one PRD requirement:

• Every API endpoint serves a PRD functional requirement
• Every DB table serves a data requirement from FRs or NFRs
• Every service boundary serves a domain responsibility from the PRD scope
• Every async flow serves a PRD requirement
• Every error handling strategy serves a PRD edge case or NFR
• Every consistency decision serves a PRD requirement
• Every security boundary serves a security or compliance requirement
• Every integration boundary serves an external system requirement
• Every observability decision serves an NFR

Phase 2: Coverage

For every PRD requirement, verify it is covered by the architecture:

• Every functional requirement has at least one architectural component
• Every NFR has at least one architectural decision
• Every edge case has an error handling strategy
• Every acceptance criterion has architectural support

Phase 3: Scalability

• Can each service scale independently?
• Are there single points of failure?
• Are there bottlenecks that prevent horizontal scaling?
• Is database scaling addressed?
• Are there unbounded data growth scenarios?

Phase 4: Consistency

• Is the consistency model explicit for each data domain?
• Are eventual consistency windows acceptable for the use case?
• Are race conditions identified and mitigated?
• Is idempotency designed for operations that require it?
• Are distributed transaction boundaries clear?
• Is the deduplication strategy sound?
• Are retry semantics defined for all async operations?
• Is the outbox pattern used where needed?
• Are saga/compensation patterns defined for multi-step operations?

Phase 5: Security

• Are authentication boundaries clearly defined?
• Is authorization modeled correctly?
• Is service-to-service authentication specified?
• Is token propagation defined?
• Is tenant isolation defined (for multi-tenant systems)?
• Is secret management addressed?
• Are there data exposure risks in API responses?
• Is audit logging specified for sensitive operations?

Phase 6: Integration

• Are all external system integrations identified?
• Is the integration pattern appropriate for each?
• Are rate limits and quotas addressed?
• Are failure modes defined for each integration?
• Are retry strategies defined for transient failures?
• Is data transformation between systems addressed?

Phase 7: Observability

• Are logs, metrics, and traces all specified?
• Is correlation ID propagation defined across services?
• Are SLOs defined for critical operations?
• Are alert conditions and thresholds specified?
• Can the system be debugged end-to-end from logs and traces?

Phase 8: Data Integrity

• Are there scenarios where data could be lost?
• Are transaction boundaries appropriate?
• Are there scenarios where data could become inconsistent?
• Is data ownership clear?
• Are cascading deletes or updates handled correctly?

Phase 9: Over-Engineering Detection

• Services that could be modules
• Patterns applied without PRD justification
• Storage choices exceeding requirements
• Async processing where sync would suffice
• Abstraction layers without clear benefit
• Consistency guarantees stronger than requirements
• Security boundaries more complex than the threat model
• Observability granularity beyond operational need

Phase 10: Under-Engineering Detection

• Missing error handling for PRD edge cases
• Missing idempotency for operations requiring it
• Missing NFR accommodations
• Missing async processing for non-blocking requirements
• Missing security boundaries where the PRD requires them
• Missing observability for critical operations
• Missing consistency model specification
• Missing integration failure handling
• Missing retry strategies for external dependencies

Review Output Format

After completing all audit phases, produce a single structured review section. Append or update the ## Architecture Review section in docs/architecture/{feature}.md with the following fixed groups:

## Architecture Review

### Traceability Gaps

List every architectural element that cannot be traced to a PRD requirement, and every PRD requirement not covered by the architecture.

| Element / Requirement | Issue | Proposed Fix |
|----------------------|-------|-------------|
| ... | Untraceable / Uncovered | ... |

### Missing Decisions

List required architectural decisions that are absent or incomplete.

- [ ] ...

### Over-Engineering

List elements that exceed what the PRD requires.

- ... (specific item, why it is over-engineered, proposed simplification)

### Under-Engineering

List PRD requirements that lack adequate architectural support.

- ... (specific requirement, what is missing, proposed addition)

### Risks

| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|------------|
| ... | High/Medium/Low | High/Medium/Low | ... |

### Required Revisions

Numbered list of all changes that MUST be applied before handoff:

1. ...
2. ...

After producing the review, apply all Required Revisions directly to docs/architecture/{feature}.md.

Gate Decision

After applying revisions, evaluate the final state:

• PASS — All revisions applied, no remaining blockers
• CONDITIONAL PASS — Minor gaps remain but do not block Planner handoff
• FAIL — Significant revision required; return to design-architecture

Record the gate decision at the end of the Architecture Review section.

If FAIL, do NOT proceed to finalize-architecture. The architecture must be redesigned in design-architecture first.

If PASS or CONDITIONAL PASS, proceed to finalize-architecture.

Guardrails

This is a pure validation and revision skill.

Do:

• Audit the architecture silently and produce a single batch review
• Validate traceability, scalability, consistency, security, integration, observability
• Detect over-engineering and under-engineering
• Propose specific fixes for all identified issues
• Apply all fixes directly to docs/architecture/{feature}.md
• Record the gate decision

Do not:

• Ask questions interactively
• Change PRD requirements or scope
• Design architecture from scratch
• Make implementation-level decisions
• Break down tasks or create milestones
• Write test cases
• Produce any file artifact other than docs/architecture/{feature}.md

Transition

If gate decision is PASS or CONDITIONAL PASS, invoke finalize-architecture for final completeness check and format validation.