/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):

*.ts

*.js

canon/javascript/typescript/SUMMARY.md

canon/javascript/js-safety/SUMMARY.md

canon/javascript/js-perf/SUMMARY.md

canon/javascript/js-internals/SUMMARY.md

canon/javascript/functional/SUMMARY.md

angular.json

canon/angular/angular-arch/SUMMARY.md

canon/angular/angular-core/SUMMARY.md

canon/angular/angular-perf/SUMMARY.md

canon/angular/rxjs/SUMMARY.md

package.json

"react"

canon/javascript/react-state/SUMMARY.md

canon/javascript/react-test/SUMMARY.md

canon/javascript/reactivity/SUMMARY.md

pom.xml

build.gradle

canon/java/SUMMARY.md

*.py

canon/python/python-advanced/SUMMARY.md

canon/python/python-idioms/SUMMARY.md

canon/python/python-patterns/SUMMARY.md

canon/python/python-protocols/SUMMARY.md

*.cs

*.csproj

canon/csharp/csharp-depth/SUMMARY.md

canon/csharp/type-systems/SUMMARY.md

canon/csharp/async/SUMMARY.md

.tsx

.jsx

canon/ui-ux/components/SUMMARY.md

canon/ui-ux/usability/SUMMARY.md

canon/ui-ux/tokens/SUMMARY.md

d3

canon/visualization/d3/SUMMARY.md

canon/visualization/charts/SUMMARY.md

canon/visualization/dashboards/SUMMARY.md

canon/database/sql/SUMMARY.md

canon/database/sql-perf/SUMMARY.md

canon/security/security-mindset/SUMMARY.md

canon/security/owasp/SUMMARY.md

canon/security/web-security/SUMMARY.md

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

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

List<T>

ArrayList<T>

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.