Agent spent 45 minutes rebuilding OAuth because it missed AUTH.md

Your agent just spent 45 minutes implementing OAuth from scratch because it "couldn't find the authentication docs." The docs were right there in your codebase — in a file called AUTH.md.

This happens because agents don't know what they don't know. They'll reinvent JWT validation, rebuild your database schema, and rewrite your entire error handling system rather than ask if you already solved this.

The fix is stupidly simple: build your agent a discovery system.

The Three-File Discovery Pattern

Create these three files in your project root:

DISCOVERY.md
PATTERNS.md
DECISIONS.md

DISCOVERY.md is your agent's treasure map. List every important file, where to find examples of common patterns, and what already exists:

# Discovery Guide

## Authentication
- Implementation: `/lib/auth.js`
- Examples: `/tests/auth.test.js`
- Config: `/config/auth.json`

## Database
- Schema: `/db/schema.sql`
- Models: `/models/`
- Migrations: `/db/migrations/`

## Error Handling
- Base classes: `/lib/errors.js`
- Examples: search for "CustomError" in codebase

PATTERNS.md captures your architectural decisions. How do you structure API responses? What's your naming convention for database tables? How do you handle async operations?

# Code Patterns

## API Responses
Always return: `{ success: boolean, data: any, error?: string }`

## Database Tables
Naming: singular nouns (`user`, not `users`)
Primary keys: always `id`
Timestamps: `created_at`, `updated_at`

## Error Handling
Throw custom errors, catch at route level
Log errors with request ID for tracing

DECISIONS.md explains why you chose what you chose. Why Express over Fastify? Why PostgreSQL over MongoDB? Why that particular authentication flow?

This stops your agent from second-guessing your architecture and rebuilding systems you already have.

The Discovery Prompt

Add this to your agent's system prompt:

Before implementing anything new:
1. Check DISCOVERY.md for existing implementations
2. Check PATTERNS.md for architectural guidelines
3. Check DECISIONS.md for context on technical choices
4. If you can't find guidance, ask before building

Pro tip: Update these files every time your agent builds something new. Make it part of your agent's completion ritual. "I built X, here's how to find it next time."

I've seen this pattern cut agent implementation time by 60% because it stops them from reinventing your wheel every single conversation.

The discovery files become your agent's institutional memory. Without them, every conversation starts from zero.