NO PUBLIC API WITHOUT DOCUMENTATION. NO COMPLEX LOGIC WITHOUT COMMENTS. NO DOCUMENTATION THAT DOESN'T MATCH THE CODE.

YOU CANNOT:
- Say "documentation is done" — verify every code example runs, every link works, every setup step succeeds
- Copy-paste code examples without testing them — stale examples are worse than no examples
- Document what you PLAN to build — only document what EXISTS and WORKS
- Write "see code for details" — if the reader needs code, the documentation failed
- Skip the Quick Start — the first 60 seconds determines if anyone reads further
- Leave TODO or "Coming soon" in documentation — remove it or write it now
- Document for yourself — document for someone who joins tomorrow
- Skip testing setup instructions — run them from scratch in a clean environment

1. Can a new developer get the project running in under 5 minutes following only the README?
2. Does every public function/endpoint have documented: purpose, parameters, return value, errors, and example?
3. Is there an architecture overview that fits on one page?
4. If every team member was unavailable, could someone maintain this project from docs alone?
5. When was each documentation page last verified against the actual code?
6. Are there any broken links, stale screenshots, or wrong version numbers?
7. Does the README answer the three questions every visitor has: What? Why? How?
8. Are error messages documented with solutions (not just descriptions)?
9. Is the documentation searchable and navigable?
10. Would someone starting today be productive in one day?

# Project Name

One line: what this does and who it's for.

## Quick Start

Three commands or fewer to get running:

```bash
# Install
npm install

# Configure
cp .env.example .env

# Run
npm run dev

**README quality rubric:**

| Criterion | 🔴 Failing | 🟡 Adequate | 🟢 Excellent |
|-----------|-----------|------------|-------------|
| Time to running | > 15 min | 5-15 min | < 5 min |
| Setup steps | "Figure it out" | Steps listed | Steps tested + troubleshooting |
| Architecture | None | Text description | Diagram + component table |
| Examples | None | Basic | Copy-pasteable, tested |
| Env vars | Undocumented | Listed | Listed with types + defaults |

### API Documentation

For each endpoint or public function:

```markdown
### `POST /api/users`

Create a new user account.

**Authentication:** Required (Bearer token)

**Request Body:**
| Field | Type | Required | Validation | Description |
|-------|------|----------|-----------|-------------|
| email | string | Yes | Valid email format | User's email address |
| name | string | Yes | 1-100 characters | Display name |
| role | string | No | "user" or "admin" | Default: "user" |

**Response (201 Created):**
```json
{
  "data": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "role": "user",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "name": "Jane Doe"}'

### Architecture Documentation

```markdown
# Architecture: [System Name]

## Overview
[2-3 sentences: what the system does and how]

## System Diagram
[ASCII diagram, Mermaid, or link to diagram tool]

## Components
| Component | Responsibility | Technology | Owner |
|-----------|---------------|-----------|-------|
| API Gateway | Request routing, auth | Express | Backend team |
| User Service | User management | Node.js | Backend team |
| Database | Data persistence | PostgreSQL | Platform team |

## Data Flow
[Describe how data moves through the system for the primary use case]

## Key Decisions
| Decision | Rationale | Trade-offs | Date |
|----------|-----------|-----------| -----|
| PostgreSQL over MongoDB | Relational data, ACID | Less flexible schema | 2024-01 |
| JWT over sessions | Stateless, scalable | Token revocation complexity | 2024-01 |

## Non-Functional Requirements
| Requirement | Target | Current |
|------------|--------|---------|
| Response time (p95) | < 200ms | 150ms |
| Availability | 99.9% | 99.7% |
| Max concurrent users | 10,000 | 5,000 tested |

# GOOD: Explains WHY, not WHAT
# Process orders in batches of 100 to stay within the payment
# gateway's rate limit of 120 requests/minute. Sleep between
# batches to avoid 429 errors.
for batch in chunk(orders, 100):
    process(batch)
    sleep(60)

# BAD: States the obvious (delete these comments)
# Loop through orders
for order in orders:
    process(order)

# GOOD: Documents non-obvious behavior
def calculate_tax(amount: Decimal, state: str) -> Decimal:
    """Calculate sales tax for a given US state.

    Note: Oregon (OR) has no sales tax. Delaware (DE) has
    no sales tax but has a gross receipts tax handled separately
    by the GrossReceiptsCalculator.

    Args:
        amount: Pre-tax amount in USD
        state: Two-letter US state code (uppercase)

    Returns:
        Tax amount. Returns Decimal('0') for exempt states.

    Raises:
        ValueError: If state code is not a valid US state.
    """

# Documentation Audit: [Project Name]

## README Assessment
| Criterion | Status | Assessment |
|-----------|--------|------------|
| Quick Start (< 5 min) | ✅/❌ | |
| Architecture overview | ✅/❌ | |
| Setup instructions (tested) | ✅/❌ | |
| Environment variables | ✅/❌ | |
| Contributing guide | ✅/❌ | |

## API Documentation
| Endpoint | Documented | Examples | Error Codes | Assessment |
|----------|-----------|----------|------------|------------|
| POST /users | ✅ | ✅ | ⚠️ partial | 🟡 |

## Code Comments
| Module | WHY Comments | Stale Comments | Assessment |
|--------|-------------|---------------|------------|
| auth/ | 5 | 0 | 🟢 |
| api/ | 1 | 3 | 🟠 |

## Findings
[Standard severity format]

## Verdict: [PASS / CONDITIONAL PASS / FAIL]