| name | evidence-citation |
| description | Evidence-backed documentation patterns with source code citations. Provides guidelines for citing source files, line numbers, and code examples in technical documentation. Use when writing documentation that needs to reference actual code. |
| user-invocable | false |
Evidence Citation Patterns
Guidelines for creating evidence-backed technical documentation. Every significant claim should be traceable to actual source code.
Core Principle
Never make claims without evidence. Documentation that isn't grounded in actual code becomes stale and misleading. Always cite your sources.
Citation Formats
Single File Reference
Use when pointing to a specific file:
The system uses FastAPI for the REST API (see `app/main.py`).
Line Number Reference
Use when pointing to a specific location:
Authentication is handled by the `verify_token` function (see `auth/jwt.py:42`).
Line Range Reference
Use when referring to a block of code:
The checkout workflow is implemented in `services/checkout.py:15-89`.
Pattern/Glob Reference
Use when referring to multiple files:
All API routes follow RESTful conventions (see `routes/**/*.ts`).
Directory Reference
Use when referring to a module or component:
User management is handled by the auth module (see `src/auth/`).
Citation Levels
Level 1: Inline Citation (Minimum)
For quick references where the reader can easily find the code:
The system uses PostgreSQL for persistence (see `docker-compose.yml`).
Level 2: Citation with Context (Recommended)
Include brief context about what to look for:
Rate limiting is configured at 100 requests per minute (see `middleware/ratelimit.ts:23` — the `RATE_LIMIT` constant).
Level 3: Citation with Code Sample (Best)
Include actual code for critical documentation:
The system uses FastAPI for the REST API (see `app/main.py`):
\`\`\`python
from fastapi import FastAPI
app = FastAPI(title="MyAPI", version="1.0.0")
\`\`\`
When to Use Each Level
| Situation | Citation Level | Example |
|---|
| Well-known patterns | Level 1 | "Uses React hooks (see hooks/)" |
| Configuration values | Level 2 | "Timeout set to 30s (see config.ts:15 — REQUEST_TIMEOUT)" |
| Critical architecture | Level 3 | Full code sample with file reference |
| Security mechanisms | Level 3 | Full code sample showing implementation |
| Complex algorithms | Level 3 | Full code sample with explanation |
Evidence Gathering Process
Step 1: Identify Claims
List all factual statements you're making:
- "The system uses X framework"
- "Authentication works via Y mechanism"
- "Data flows from A to B"
Step 2: Find Evidence
For each claim, locate the source code that supports it:
grep -r "from fastapi" --include="*.py"
grep -r "DATABASE_URL" --include="*.env*"
grep -rn "def authenticate" --include="*.py"
Step 3: Verify Accuracy
Before citing, verify:
Step 4: Add Citations
Insert citations using appropriate level based on importance.
Common Citation Patterns
Architecture Claims
The application follows a layered architecture:
- **Presentation layer**: API routes (see `routes/`)
- **Business logic**: Service classes (see `services/`)
- **Data access**: Repository pattern (see `repositories/`)
Technology Claims
The frontend is built with React 18 and TypeScript (see `package.json:12-15`):
\`\`\`json
{
"dependencies": {
"react": "^18.2.0",
"typescript": "^5.0.0"
}
}
\`\`\`
Configuration Claims
The API rate limits requests to 1000/hour per IP (see `config/ratelimit.ts:8`):
\`\`\`typescript
export const RATE_LIMIT = {
windowMs: 60 * 60 * 1000, // 1 hour
max: 1000
};
\`\`\`
Workflow Claims
The checkout process follows these steps (see `services/checkout.ts:45-120`):
1. Validate cart items (`validateCart()` at line 48)
2. Calculate totals (`calculateTotals()` at line 62)
3. Process payment (`processPayment()` at line 78)
4. Create order (`createOrder()` at line 95)
Anti-Patterns to Avoid
Vague References
# Bad
The system handles authentication.
# Good
Authentication uses JWT tokens validated by middleware (see `middleware/auth.ts:15-30`).
Outdated Line Numbers
# Bad (if code has changed)
See `auth.ts:42` for the login function.
# Better (more resilient)
See the `handleLogin` function in `auth.ts`.
Missing Critical Evidence
# Bad
The API is secure.
# Good
The API implements security measures including:
- JWT authentication (see `middleware/auth.ts`)
- Rate limiting (see `middleware/ratelimit.ts`)
- Input validation (see `validators/`)
- HTTPS enforcement (see `server.ts:12`)
Invented Code Samples
# Bad (making up code)
\`\`\`python
# This is how it probably works
def authenticate(user):
return check_password(user)
\`\`\`
# Good (actual code from repo)
\`\`\`python
# From auth/service.py:23-28
def authenticate(credentials: LoginCredentials) -> AuthResult:
user = self.user_repo.find_by_email(credentials.email)
if not user or not verify_password(credentials.password, user.password_hash):
raise InvalidCredentialsError()
return AuthResult(user=user, token=self.create_token(user))
\`\`\`
Quality Checklist
Before finalizing documentation, verify:
Version: 1.0
Last Updated: 2026-01-22