feature-knowledge

Feature Knowledge Base Creation

Iron Law

Capture the institutional knowledge that lives in developers' heads — the things obvious to them but invisible to newcomers.

A feature knowledge entry exists to save the NEXT agent from rediscovering patterns that span multiple files, modules, or layers. If it's obvious from a single file read, don't capture it.

---

The Four Phases

Follow these four phases in order. Do not skip ahead.

Phase 1: Scan

Map the landscape. Get a high-level understanding before going deep.

• Use Glob to discover directory structure and file organization
• Identify language(s), framework(s), and major dependencies
• Locate key entry points, configuration files, and existing documentation
• Note how the code is organized — monorepo, modules, layers, etc.

Goal: Answer "Where does the code related to this area live, and how is it structured?"

Phase 2: Extract

Go deep. Read the actual code and pull out the real patterns.

• Read key files using Read
• Use Grep to find recurring patterns across the codebase
• Trace data flow: how does information move through the system?
• Identify naming conventions, structural patterns, error handling approaches
• Look for implicit rules — things the team clearly follows but never wrote down
• Pay attention to what's consistent (conventions) vs. what varies (knowledge gaps)
• Look at how similar things are implemented — find ALL instances and see what they share

For complex domains, go further:

• Map core entities and their relationships
• Identify decision points — where does business logic branch?
• Extract implicit knowledge — what's obvious to current developers but invisible to newcomers?
• Document state transitions, business rules, and edge case handling

Self-check before moving on:

• "Am I understanding the full scope of what's being requested?"
• "What connections am I seeing that weren't obvious initially?"
• "Are there patterns I'm missing because I'm too focused on one area?"