opencode-workflow/skills/challenge-code-design/SKILL.md

name	description
challenge-code-design	Silent audit and batch review of code design decisions. Validates traceability to architecture, interface completeness, model coverage, error design alignment, and detects over/under-abstraction. Updates the single code design file in place.

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

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

Primary Input

• docs/code-design/{date}-{feature}.md
• docs/architecture/{date}-{feature}.md

Primary Output (STRICT PATH)

• Updated docs/code-design/{date}-{feature}.md

This is the only file artifact in the Code Design 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 code design document and architecture document 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 code design 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: Architecture Traceability

For every code design element, verify it traces back to an architecture component:

• Every package maps to a service boundary or domain in the architecture
• Every repository interface maps to a DB table in the architecture
• Every service interface maps to a service boundary in the architecture
• Every handler maps to an API endpoint in the architecture
• Every domain entity maps to a DB table in the architecture
• Every DTO maps to an API request/response in the architecture
• Every error type maps to the architecture error model
• Every async publisher/consumer maps to an async flow in the architecture

Phase 2: Architecture Coverage

For every architecture component, verify it is covered by the code design:

• Every DB table has a migration spec, model struct, and repository interface
• Every API endpoint has a handler, service method, request DTO, and response DTO
• Every service boundary has a package, service interface, and constructor
• Every async flow has a publisher, consumer, and message struct
• Every error category has a Go error type
• Every external integration has a port interface

Phase 3: Interface Completeness

For every interface definition:

• All CRUD operations needed by the architecture are present
• All query operations needed by the architecture are present
• Method signatures follow consistent conventions (context.Context first, error in return)
• Interface segregation: no interface has methods that some consumers don't need
• Return types are consistent (pointer vs value, slice vs nil)

Phase 4: Model Completeness

For every struct definition:

• All fields from architecture schema are present
• Field types are appropriate for Go (UUID, time.Time, etc.)
• Struct tags are complete and correct (json, db, validate)
• Domain entity has no infrastructure concerns (no DB tags, no JSON tags for internal fields)
• DB model has appropriate DB tags
• DTO has appropriate JSON tags and validation tags
• Mapping functions exist for all layer boundaries

Phase 5: Error Design Alignment

• Every error code in the architecture error model has a corresponding Go error type
• Error wrapping convention is consistent across all layers
• HTTP status mapping covers all error codes in the architecture API contract
• Sentinel errors are defined for all common cases
• Error response format matches architecture error model

Phase 6: Over-Abstraction Detection

• Interfaces with only one implementation and no testing need
• Extra abstraction layers not justified by the architecture
• Generic patterns applied where specific patterns would be simpler
• Unnecessary indirection (wrapper types, adapter layers without clear boundary)
• Over-engineered DI when simple constructor injection suffices

Phase 7: Under-Abstraction Detection

• Missing interfaces for testability (direct struct usage where interface is needed for mocking)
• Missing repository interfaces for data access
• Missing service boundaries where domain logic is leaked into handlers

Review Output Format

The results of the audit must be written directly into the # Code Design Review section of docs/code-design/{date}-{feature}.md using this exact format:

## Code Design Review

### 1. Traceability & Coverage
- [PASS/FAIL] All architecture components covered.
- [Findings]: ...

### 2. Interface & Model Quality
- [PASS/FAIL] Signatures and tags are complete and idiomatic.
- [Findings]: ...

### 3. Error & DI Design
- [PASS/FAIL] Error model aligned and DI explicit.
- [Findings]: ...

### 4. Abstraction Balance
- [PASS/FAIL] No over/under abstraction detected.
- [Findings]: ...

### 5. Final Verdict
- [APPROVED/REJECTED]
- [Reason]: ...

Process

1. Read input documents in full
2. Perform all 7 audit phases silently
3. Apply all necessary fixes directly to the code design sections (Project Structure, Interfaces, Models, etc.) to resolve failures
4. Write the summary review into the # Code Design Review section
5. Mark the final verdict

Guardrails

Do:

• Audit silently and apply fixes in batch
• Use the fixed review format
• Ensure 1:1 traceability to architecture
• Fix all detected failures before finalizing the review

Do not:

• Ask interactive questions
• Propose changes without applying them
• Modify architecture decisions
• Create new files