/structure [path]

/​structure [path]

Design data structures and architecture. Context-aware: maps existing code or creates new types from plan.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"structure","started":"'$(date -Iseconds)'"}' > .claude/​active-workflow.json

Mode Detection

if path points to existing code:
    MODE = "map"      → Analyze and redesign
else if .claude/​plans/ has active plan:
    MODE = "create"   → Create types from plan
else:
    ERROR: Need either existing code path or plan

---

Step 0: Load Expert Guidance

Before starting either mode, read these canon skills and apply their principles throughout:

Always load (base brain — all 10):

1. canon/​clarity/​SUMMARY.md
2. canon/​pragmatism/​SUMMARY.md
3. canon/​simplicity/​SUMMARY.md
4. canon/​composition/​SUMMARY.md
5. canon/​distributed/​SUMMARY.md
6. canon/​data-first/​SUMMARY.md
7. canon/​correctness/​SUMMARY.md
8. canon/​algorithms/​SUMMARY.md
9. canon/​abstraction/​SUMMARY.md
10. canon/​optimization/​SUMMARY.md

Auto-detect domain canon (check files, load matches):

If a skill file doesn't exist (not installed in this project), skip it and continue. List loaded experts in EXPERTS_LOADED. In EXPERT_DECISIONS, show each specific structural decision an expert drove.

Step 0b: Learn From Past Mistakes

Read both lessons files if they exist:

1. .claude/​universal-lessons.md — universal patterns (ships with skills, applies to all projects)
2. .claude/​lessons.md — project-specific patterns (accumulated from this project's runs)

Apply relevant lessons to your structural design:

• DESIGN entries → avoid these architectural mistakes in your target state
• LOGIC entries → design types/​interfaces that make these bug patterns impossible (e.g., validated newtypes instead of raw strings for paths/​names)
• AI_SMELL entries → do not create speculative types/​interfaces without consumers; avoid over-decomposition

If a file doesn't exist, skip it and continue.

Step 0c: Load Quality Contracts

Read .claude/​rubric/​contracts.md. This defines 7 abstract types for boundary enforcement. Use them during boundary analysis in both modes.

---

MODE: Map (Existing Code)

Analyze existing code, diagram relationships, design improvements.

Step 1: Map Current Architecture

Read all files in target. Output a diagram:

## Architecture: [target]

CURRENT_STATE:
┌─────────────┐     ┌─────────────┐
│ UserService │────▶│  AuthStore  │
│             │     │             │
│ - getUser() │     │ - token     │
│ - saveUser()│     │ - validate()│
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│   User      │     │   Session   │
│ (interface) │     │ (interface) │
└─────────────┘     └─────────────┘

DEPENDENCIES:
- UserService → AuthStore (tight coupling)
- UserService → User (data)
- AuthStore → Session (data)

ISSUES_FOUND:
- [issue]: [why it matters]

PURITY_CHECK:
- [module]: pure ✓ | impure ✗ (calls [I/​O function] directly)
  For each impure module: can business logic be extracted into pure functions
  that take data and return data, with I/​O pushed to callers?

Step 2: Apply Canon Wisdom

Review against principles from the masters:

Step 3: Design Target State

TARGET_STATE:
┌─────────────┐     ┌─────────────┐
│ UserService │     │ AuthService │
│             │     │ (new)       │
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────────────────────────┐
│         UserRepository          │
│         (extracted)             │
└─────────────────────────────────┘

CHANGES_NEEDED:
- Extract AuthService from AuthStore
- Create UserRepository interface
- Inject dependencies via constructor

EXPERTS_LOADED: [list of skill names actually read]
EXPERT_DECISIONS:
- [expert-skill]: [specific structural decision it drove]

Map Mode Output

## Structure: [target]

MODE: map

CURRENT_STATE:
[diagram]

ISSUES_FOUND:
- [issue]: [description]

TARGET_STATE:
[diagram]

CHANGES_NEEDED:
- [change 1]
- [change 2]

QUALITY_CONTRACTS:
| Boundary | Abstract Type | Contract | Construction Check |
|----------|--------------|----------|--------------------|
| {boundary} | {type} | {what must be true} | {missing contract = issue} |

EXPERTS_LOADED: [list of skill names actually read]
EXPERT_DECISIONS:
- [expert-skill]: [specific decision it drove]

STRUCTURE_COMPLETE

---

MODE: Create (New Types from Plan)

Create actual type files from an approved plan.

Requirements

1. CREATE TYPE FILES - Use Write tool to create actual .ts files
2. EVERY TYPE FROM PLAN - Create all types listed in plan's TYPES section
3. NO PLACEHOLDER TYPES - Every field must have a real type, not 'any' or 'unknown'
4. INVARIANTS AS COMMENTS - Document invariants as JSDoc comments

Craft Standards

Types must look like they were designed by a skilled human engineer:

Reject:

• Over-engineered type hierarchies
• Generic wrappers when simple types work
• Speculative fields "in case we need them later"
• Partial<T> abuse creating unclear contracts

Embrace:

• Types that document the domain
• Minimal fields - only what's actually used
• Self-documenting names
• Impossible states made unrepresentable

Elegance Principles

Boundary Analysis (Create Mode)

For each function/​module being created, identify boundaries using the detection signals from .claude/​rubric/​contracts.md:

• Where does user input enter? → ValidatedInput
• Where are file paths constructed? → SafePath
• Where are errors caught and re-thrown? → CausedError
• Where are secrets handled? → Secret
• Where is external data read? → ExternalData
• Where could operations hang or grow unbounded? → BoundedOperation
• Where are state mutations that could be retried? → IdempotentAction

Output a QUALITY_CONTRACTS table in the structure output.

Create Mode Output

## Structure: [feature]

MODE: create

TYPES_CREATED:
- src/​types/​user.ts: User, UserPublic, CreateUserInput
- src/​types/​auth.ts: AuthToken, TokenPayload

INVARIANTS_DOCUMENTED:
- User: email must be unique, password_hash never exposed
- AuthToken: expires_at must be in future

QUALITY_CONTRACTS:
| Boundary | Abstract Type | Contract | Construction Check |
|----------|--------------|----------|--------------------|
| {where data enters/​leaves} | {abstract type} | {what must be true} | {EXPORT_FUNCTION or EXPORT_TYPE to verify} |

EXPERTS_LOADED: [list of skill names actually read]
EXPERT_DECISIONS:
- [expert-skill]: [specific decision it drove]

STRUCTURE_COMPLETE

---

FORBIDDEN (Phase FAILS if detected)

• Using 'any' or 'unknown' types
• TODO comments in types
• Describing without creating (create mode)
• Skipping diagram (map mode)
• No STRUCTURE_COMPLETE marker

🛑 MANDATORY STOP

After completing structure analysis/​creation:

• DO NOT proceed to /​implementation
• DO NOT start writing implementation code

Your turn ends here. Output STRUCTURE_COMPLETE and STOP.