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

---
name: challenge-code-design
description: "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:

```markdown
## 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