KNOW BEFORE YOU DO

Claude must demonstrate understanding before making changes.
If Claude doesn't know → Claude asks or surveys.
If Claude assumes → Claude is wrong.

# Check if we've already surveyed this project
if [ -f "SOURCE-OF-TRUTH.md" ]; then
    echo "SOURCE-OF-TRUTH.md exists - reading current state"
    # Read and validate the existing source of truth
else
    echo "No SOURCE-OF-TRUTH.md found - FULL SURVEY REQUIRED"
    # Trigger Phase 1
fi

# Check for existing CLAUDE.md
if [ -f "CLAUDE.md" ]; then
    echo "CLAUDE.md exists - reading project context"
fi

# Create survey workspace
mkdir -p .contractor-survey/{reports,evidence}
echo "Survey started: $(date)" > .contractor-survey/survey.log

ROLE: Map the complete project structure
OUTPUT: .contractor-survey/reports/structure.md

TASKS:
1. Create complete directory tree (excluding node_modules, .git, dist)
2. Identify entry points (index.*, main.*, app.*, server.*)
3. Document the naming conventions used
4. Identify frameworks and major dependencies
5. Note any unusual or non-standard organization
6. Find all configuration files and their purposes

DELIVERABLE FORMAT:
# Structure Report

## Directory Tree
[tree output]

## Entry Points
- Frontend: [path]
- Backend: [path]
- Other: [list]

## Frameworks Detected
- [name]: [version] - [purpose]

## Configuration Files
| File | Purpose | Critical Settings |
|------|---------|-------------------|

## Non-Standard Patterns
- [description]

ROLE: Trace all connections and integrations
OUTPUT: .contractor-survey/reports/connections.md

TASKS:
1. Find all API endpoints (internal and external)
2. Identify database connections and schemas
3. Map WebSocket/real-time connections
4. Trace authentication flows
5. Document third-party service integrations
6. Find all environment variables and their purposes
7. Map inter-service communication patterns

DELIVERABLE FORMAT:
# Connection Report

## Internal APIs
| Endpoint | Method | Handler | Purpose |
|----------|--------|---------|---------|

## External APIs
| Service | Auth Method | Env Vars | Purpose |
|---------|-------------|----------|---------|

## Database Connections
- Type: [PostgreSQL/MongoDB/etc]
- Connection string var: [name]
- Schema location: [path]

## Real-Time Connections
- Protocol: [WebSocket/SSE/MQTT]
- Handler: [file:line]
- Events: [list]

## Environment Variables
| Variable | Purpose | Example | Required |
|----------|---------|---------|----------|

ROLE: Validate and document all operational commands
OUTPUT: .contractor-survey/reports/operations.md

TASKS:
1. Find ALL ways to start development servers
2. Find ALL database migration methods
3. Find ALL deployment methods
4. Find ALL test commands
5. Find ALL build commands
6. TEST each command (dry-run if destructive)
7. Document which commands are CANONICAL (actually work)

DELIVERABLE FORMAT:
# Operations Report

## Development Server
CANONICAL COMMAND: [the one that actually works]
TESTED: [yes/no]
RESULT: [output summary]

Alternative methods found (may be outdated):
- [command] - Status: [works/broken/deprecated]

## Database Operations
CANONICAL MIGRATION: [command]
CANONICAL SEED: [command]
Schema location: [path]

## Deployment
CANONICAL DEPLOY: [command or process]
CI/CD: [yes/no - describe]
Manual steps required: [list]

## Testing
CANONICAL TEST: [command]
Coverage: [percentage if available]

## Build
CANONICAL BUILD: [command]
Output location: [path]

ROLE: Understand current project state and history
OUTPUT: .contractor-survey/reports/state.md

TASKS:
1. Check git status and recent commits
2. Identify active branches and their purposes
3. Find open issues/todos in code
4. Check for existing documentation and its accuracy
5. Identify any broken or deprecated code
6. Find all TODO/FIXME/HACK comments
7. Assess test coverage and health

DELIVERABLE FORMAT:
# State Report

## Git Status
Current branch: [name]
Uncommitted changes: [yes/no - summary]
Recent commits (last 5):
- [hash] [message] [date]

## Active Branches
| Branch | Purpose | Last Commit |
|--------|---------|-------------|

## Code Health
TODOs found: [count]
FIXMEs found: [count]
HACKs found: [count]
Critical issues: [list]

## Documentation Accuracy
| Doc File | Accurate | Issues |
|----------|----------|--------|

## Test Health
Test coverage: [percentage]
Failing tests: [count]
Skipped tests: [count]

ROLE: Audit all dependencies and their relationships
OUTPUT: .contractor-survey/reports/dependencies.md

TASKS:
1. List all production dependencies
2. List all dev dependencies
3. Check for unused dependencies
4. Check for outdated dependencies
5. Check for security vulnerabilities
6. Identify circular dependencies
7. Document critical dependencies that everything depends on

DELIVERABLE FORMAT:
# Dependencies Report

## Critical Dependencies
[These are core to the application - breaking changes here break everything]
- [package]: [purpose]

## Production Dependencies
| Package | Version | Purpose | Outdated |
|---------|---------|---------|----------|

## Dev Dependencies
| Package | Version | Purpose |
|---------|---------|---------|

## Issues Found
- Unused: [list]
- Vulnerable: [list]
- Circular: [list]

# SOURCE OF TRUTH

Generated: [timestamp]
Project: [name]
Last validated: [timestamp]

## Quick Reference

### Start Development
```bash
[CANONICAL COMMAND FROM OPERATIONS REPORT]

[CANONICAL COMMAND]

[CANONICAL COMMAND or PROCESS]

[CANONICAL COMMAND]

## Phase 3: User Validation

**CRITICAL**: Before proceeding with ANY work, Claude must:

1. Present the SOURCE-OF-TRUTH.md to the user
2. Ask: "Does this accurately reflect your project? Any corrections?"
3. Update based on user feedback
4. Get explicit "yes, proceed" before continuing

```markdown
I've completed the project survey. Here's what I understand:

[Summary of key findings]

**Before I do anything else, I need you to validate this:**

1. Are the canonical commands correct?
2. Are there any integrations I missed?
3. Are there any files I should never touch?
4. Anything else I got wrong?

Once you confirm, I'll update SOURCE-OF-TRUTH.md and we can proceed.

## Assumptions Log

| Date | Assumption | Basis | Verified |
|------|------------|-------|----------|
| 2024-01-15 | Component uses React hooks | Saw useState import | Yes |
| 2024-01-15 | API uses REST not GraphQL | Found express routes | No - ASK USER |

STOP. I don't have enough information to proceed safely.

I need to know:
- [specific question 1]
- [specific question 2]

Without this, I would be guessing, and guessing breaks things.

# Update SOURCE-OF-TRUTH.md
echo "Last updated: $(date)" >> SOURCE-OF-TRUTH.md

# Log what changed
echo "- [description of change]" >> SOURCE-OF-TRUTH.md

STOP. I need to pause.

I just realized I've been assuming [X] without verification.
Before I continue, I need to:
1. Check if my assumption was correct
2. Update SOURCE-OF-TRUTH.md
3. Verify no damage was done

Let me survey the affected areas first.