Map Project

SKIPPING DISCOVERY = INCOMPLETE DOCUMENTATION = AI AGENT FAILURE

This is not optional. You cannot rationalize "good enough" without running verification checks.

Update CLAUDE.md After Installation

MANDATORY FIRST RESPONSE PROTOCOL

Before writing ANY documentation:

1. ☐ Complete Phase 0: Detect the framework
2. ☐ Complete Phase 1: Framework-specific discovery (ALL steps)
3. ☐ Create API surface inventory with counts
4. ☐ Verify >90% coverage is achievable
5. ☐ Announce: "Detected [Framework]. Starting documentation update targeting 10/10"

Writing docs without discovery = guaranteed gaps. Phase 0 + Phase 1 are NON-NEGOTIABLE.

Overview

After installing framework agents, CLAUDE.md and its imported files contain generic placeholder examples. This skill guides you to systematically discover the actual project patterns and update these files with real, project-specific information.

Core principle: Discover exhaustively, then document. Analyze ALL exports/classes/routes before writing.

Quality target: 10/10 AI agent effectiveness — documentation should enable an AI to implement features correctly on the first attempt.

Supported frameworks: Laravel, Next.js (App Router), NestJS, Expo/React Native (expo-router), Node.js monorepo.

Context Budget Limits

Your documentation MUST fit within these constraints:

If Over Budget

1. Move code examples >30 lines to "reference by path" format
2. Convert prose to tables (3x more token-efficient)
3. Consolidate overlapping sections
4. Remove redundant information between files

What Makes 10/10 Documentation

AI agents are most effective when documentation provides:

1. Step-by-Step Implementation Guides

❌ Poor (4/10): "We use controllers for API endpoints" ✅ Excellent (10/10): Numbered steps with actual code templates from the codebase

## Adding a New API Endpoint (Laravel)

### Step 1: Create the Model
```php
class ModelName extends Model
{
    use BelongsToAccount, HasUuids;
    protected $fillable = ['account_id', 'name'];
}
```

### Step 2: Create the Form Request
### Step 3: Create the Controller (thin — delegates to Service)
### Step 4: Register Routes in routes/api.php

2. Response Formats

❌ Poor: "API returns JSON" ✅ Excellent: Every response shape with types

// NestJS — Interceptor wraps all responses:
{ success: true, data: T, timestamp: string }

// Error — Exception Filter formats:
{ success: false, error: string, code: 'ERROR_CODE', details: [...] }

3. State Machines with Visual Diagrams

## Gift Redemption State Machine

pending → fulfilled ↓ cancelled

| Current | Action | New State | Who |
|---------|--------|-----------|-----|
| pending | Admin approves | fulfilled | Admin |
| pending | Admin cancels | cancelled | Admin |

4. Route/Screen Tables

❌ Poor: "Routes are in the routes folder" ✅ Excellent: Complete table with all routes

| Route | File | Type | Purpose |
|-------|------|------|---------|
| `/` | app/page.tsx | Server Component | Home page |
| `/dashboard/[id]` | app/dashboard/[id]/page.tsx | Server Component | User detail |
| `/api/users` | app/api/users/route.ts | GET, POST | User CRUD |

5. API Surface Tables

| Export | Type | Purpose |
|--------|------|---------|
| parseMarkdownToBlocks | function | Parse plan text → Block[] |
| Plan | interface | Full plan with versions |

When to Use

• Initial install: User just installed agents and CLAUDE.md has generic examples
• Project start: Beginning work on a project for the first time
• Key milestones: After major architecture changes
• Periodic refresh: User asks to "update docs" or "sync CLAUDE.md with project"

Common Rationalizations (All Wrong)

• "I already know this codebase" → STILL do Phase 1 discovery
• "The exports haven't changed much" → STILL verify counts
• "This is a small project" → STILL create all 3 required files
• "80% coverage is good enough" → NO, 90% minimum
• "I can eyeball the exports" → Use search commands, not memory
• "Wrong framework won't matter" → Phase 0 detection is MANDATORY

Phase 0: Framework Detection (MANDATORY)

Before discovery, detect the framework. Check in this order (most specific first):

Announce: "Detected [Framework]. Proceeding with framework-specific discovery."

If multiple match (e.g. monorepo containing Next.js app): use the most specific framework for the primary app. Document sub-packages separately if needed.

Phase 1: Exhaustive Discovery (MANDATORY)

Do NOT skip this phase. Follow the steps for your detected framework.

Laravel

1. Models: ls app/Models/*.php — list all, note relationships (belongsTo, hasMany, belongsToMany), scopes, casts
2. Services: ls app/Services/**/*.php — list key public methods per service
3. Jobs: ls app/Jobs/*.php — note what dispatches each (Observer, Command, other Job)
4. Observers: ls app/Observers/*.php — which model, which events (created, updated)
5. Middleware: ls app/Http/Middleware/*.php — note alias from bootstrap/app.php
6. API Resources: ls app/Http/Resources/*.php — which model each transforms
7. Form Requests: ls app/Http/Requests/*.php — key validation rules per request
8. Routes: grep "Route::" routes/api.php — extract ALL methods, paths, controllers, middleware groups
9. Commands: ls app/Console/Commands/*.php + schedules from routes/console.php
10. Also scan: app/Enums/, app/Traits/, app/Contracts/, app/Mail/

Next.js (App Router)

1. Page routes: find app -name 'page.tsx' -o -name 'page.ts' (or src/app/) — derive URL from path
2. API routes: find app/api -name 'route.ts' — grep for exported GET, POST, PUT, DELETE, PATCH
3. Layouts: find app -name 'layout.tsx' — note which routes each wraps
4. Server Actions: grep -r "'use server'" src --include="*.ts" --include="*.tsx" — list all action functions
5. Client Components: grep -rl "'use client'" src — identify interactive components
6. Middleware: find . -maxdepth 2 -name 'middleware.ts' — note matcher config
7. Hooks: find src/hooks -name '*.ts' -o -name '*.tsx' — list custom hooks
8. Types: grep -rh "^export interface\|^export type" src/types --include="*.ts"

NestJS

1. Modules: find src -name '*.module.ts' — note imports, exports, controllers, providers per module
2. Controllers: find src -name '*.controller.ts' — grep @Controller, @Get, @Post, @Put, @Delete, @Patch
3. Services: find src -name '*.service.ts' — list key methods
4. Entities: find src -path '*/entities/*.ts' -o -path '*/entity/*.ts' — note properties, relationships
5. DTOs: find src -path '*/dtos/*.ts' -o -path '*/dto/*.ts' — note class-validator decorators
6. Guards: find src -name '*.guard.ts' — what they protect (JWT, roles, etc.)
7. Pipes: find src -name '*.pipe.ts' — validation/transformation purpose
8. Interceptors: find src -name '*.interceptor.ts' — logging, response transform, caching
9. Filters: find src -name '*.filter.ts' — exception handling
10. Decorators: find src/common/decorators -name '*.ts' — custom metadata annotations

Expo/React Native (expo-router)

1. Screen routes: find app -name '*.tsx' ! -name '_layout.tsx' ! -name '+not-found.tsx' — derive URL from path
2. Layouts: find app -name '_layout.tsx' — navigation type (Stack, Tabs, Drawer)
3. Components: find src/components -name '*.tsx' — categorize: ui, shared, features
4. Hooks: find src -name 'use*.ts' -o -name 'use*.tsx' — global + module-specific
5. Stores: find src -name '*Store.ts' -o -name '*store.ts' — Zustand/Redux state + actions
6. API hooks: grep -rl "useQuery\|useMutation" src --include="*.ts" — React Query hooks
7. Services: find src/services -name '*.ts' — API client, storage, notifications
8. Types: grep -rh "^export interface\|^export type" src --include="*.ts" | sort | uniq
9. Platform-specific: find . -name '*.ios.tsx' -o -name '*.android.tsx' -o -name '*.web.tsx'

Node.js Monorepo

1. Packages: ls packages/*/package.json — find entry points via jq '.main, .exports'
2. Exports: grep "^export" packages/*/src/index.ts — count types, functions, constants
3. Subpath exports: find packages/*/src -name "index.ts" + check "exports" in package.json
4. TypeScript interfaces: grep -rh "^export interface\|^export type" packages/*/src --include="*.ts"
5. Route handlers: grep -r "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts"
6. State machines: Look for entities with status or state fields

Inventory Checklist (all frameworks)

Before proceeding to Phase 2, you MUST have:

• Complete list of all discoverable items with counts
• All routes/screens mapped
• All state machines identified (entities with status/state fields)
• Import/use patterns noted

Phase 2: Required Output Files

You MUST create/update these 3 files. No exceptions.

File 1: exports-reference.md (REQUIRED)

Location: .claude/claude-md-refs/exports-reference.md Target: 300-500 lines | Coverage: >90% of discovered items

Use framework-appropriate sections:

Laravel

End with Import Patterns: use App\Models\Toast;, use App\Services\ToastService;

Next.js

NestJS

Expo/React Native

Node.js Monorepo

End with Import Patterns: import { Type } from '@scope/package';

File 2: development-guide.md (REQUIRED)

Location: .claude/claude-md-refs/development-guide.md Target: 300-500 lines

Must include framework-appropriate implementation guides:

All guides must use actual code from the codebase, not placeholders.

File 3: architecture.md (REQUIRED)

Location: .claude/claude-md-refs/architecture.md Target: 300-500 lines

All frameworks need these core sections:

1. Dependency/Import Graph — ASCII diagram showing how components depend on each other
2. Request/Data Lifecycle — Flow from entry to response
3. Routes/Screens Table — ALL routes with methods, handlers/files, auth requirements
4. State Machines — ASCII diagram + transition table for each stateful entity
5. Key Subsystems — 1 paragraph + key files per major subsystem

Framework-specific additions:

File 4: Update CLAUDE.md

Add imports and Quick Reference table:

## Project Documentation

@.claude/claude-md-refs/architecture.md
@.claude/claude-md-refs/development-guide.md
@.claude/claude-md-refs/exports-reference.md

## Quick Documentation Reference

| Need Help With | See File |
|----------------|----------|
| Adding features, endpoints, screens | development-guide.md |
| Understanding system structure, flows | architecture.md |
| Finding models, services, hooks, exports | exports-reference.md |

Phase 3: Verification (MANDATORY)

Do NOT mark complete until ALL checks pass.

Check 1: API Surface Coverage (>90%)

Run framework-appropriate count:

FAIL if: Coverage < 90%. Go back to Phase 1.

Check 2: Context Budget

wc -l CLAUDE.md .claude/claude-md-refs/*.md

FAIL if: CLAUDE.md > 1,000 lines, any import > 500, total > 2,500.

Check 3: Required Sections

exports-reference.md: Has table for EACH category, has Import/Use Patterns section development-guide.md: Has "Adding a New X" with numbered steps and actual code architecture.md: Has dependency graph, request lifecycle, route/screen table, state machines (if any)

Check 4: No Duplicates

No information duplicated between CLAUDE.md and import files, or between import files.

Check 5: AI Effectiveness Test

Can an AI agent now:

• Find any model/service/hook/export by searching exports-reference.md?
• Add a new feature by following development-guide.md step-by-step?
• Understand the system architecture from architecture.md?
• Know which file to read for any task from CLAUDE.md Quick Reference?

If ANY answer is "no", the documentation is incomplete.

Quality Checklist (Must Score 10/10)

Total: 10/10 required to complete this skill.

Common Mistakes

Failure Modes

Failure Mode 1: Skipping Discovery

Symptom: Writing docs immediately, missing 40%+ of items Fix: Phase 1 is MANDATORY. Complete inventory before writing ANY documentation.

Failure Mode 2: Wrong Framework Detection

Symptom: Using grep "^export" on a Laravel project, or scanning app/Models/ on a Next.js project Fix: Phase 0 detection is MANDATORY. Check files in priority order.

Failure Mode 3: Generic Templates

Symptom: Copy-pasting skill templates without actual project code Fix: Every code example must come from the actual codebase. No placeholders.

Failure Mode 4: Over Budget

Symptom: CLAUDE.md > 1000 lines, context bloat Fix: Tables > prose, reference by path for code >30 lines, consolidate sections.

Failure Mode 5: Self-Assessing "Good Enough"

Symptom: Marking complete at 70% coverage without running verification commands Fix: Run ALL verification checks. Must pass ALL 5 objectively.

Failure Mode 6: No State Machines

Symptom: Listing states without visual diagram Fix: Add ASCII diagram + transition table for every entity with states.

Quick Workflow Summary

PHASE 0: DETECT FRAMEWORK
├── Check composer.json+artisan → Laravel
├── Check next.config.* → Next.js
├── Check nest-cli.json/@nestjs/core → NestJS
├── Check app.json(expo)+_layout.tsx → Expo/React Native
├── Check packages/*/package.json → Node.js monorepo
└── Announce detected framework

PHASE 1: DISCOVERY (framework-specific, do not skip)
├── Scan all classes/files/exports per framework steps
├── Map all routes/screens
├── Identify state machines
└── Create inventory with counts

PHASE 2: DOCUMENTATION (3 required files)
├── CREATE exports-reference.md (>90% coverage, framework tables)
├── CREATE development-guide.md (step-by-step, actual code)
├── CREATE architecture.md (diagrams, routes, flows)
└── UPDATE CLAUDE.md (add @imports, keep <1000 lines)

PHASE 3: VERIFICATION (all must pass)
├── API surface coverage >90%
├── Context budget met (<2500 lines total)
├── All required sections present
├── No duplicates between files
└── AI effectiveness test passes

COMPLETE: Announce final quality score (must be 10/10)

Completion Announcement

Documentation update complete.

**Framework:** [Laravel/Next.js/NestJS/Expo/Node.js monorepo]

**Quality Score: X/10**
- API Surface Coverage: X/2 (Y% of Z items documented)
- Implementation Guidance: X/2
- State/Workflow Diagrams: X/2
- Routes/Screens: X/2
- Context Efficiency: X/2

**Files created/updated:**
- exports-reference.md: X lines
- development-guide.md: X lines
- architecture.md: X lines
- CLAUDE.md: X lines
- Total: X lines (within 2,500 budget)

**Verification passed:** All 5 checks complete.

This skill ensures documentation enables AI agents to implement features correctly on the first attempt — across Laravel, Next.js, NestJS, Expo/React Native, and Node.js monorepo projects.