Tier 1 vs Tier 2 vs Tier 3: when each FSE file earns its place

he failure mode on both ends is real. Too few files and context gets lost. Too many and you've built a documentation bureaucracy nobody maintains, which rots into being wrong, which is worse than absent.

Here's the rule FSE uses to decide.

Tier 1 — always. The three foundation files.

Every FSE project has exactly three, from the first session:

• FSE.md — architecture, stack, structure, constraints, standing orders. The constitution.
• FSE_STATE.md — session history, build state, decision log, lessons learned, technical debt. What's happened and where things stand.
• FSE_DISCOVERY.md — the initial audit: infrastructure, gaps, starting conditions.

These are not optional and they don't wait for the project to grow. They're the minimum that makes a project an FSE project. A solo script and a fourteen-module monolith both carry these three. The AI reads them at the start of every session — that's the entire mechanism by which context survives between sessions.

Tier 2 — when needed. Created on a trigger, not a schedule.

Five files that exist only when the project earns them:

• FSE_POLICE.md — project-specific absolute rules. The things that caused real pain and must never recur.
• FSE_PACKAGES.md — approved dependency registry. Exact versions, banned packages, why.
• FSE_UI.md — design language, component patterns, CSS architecture.
• FSE_PACKAGES.md and FSE_SCHEMA.md — entity patterns, database conventions, naming.
• PATTERNS.md — reusable patterns extracted from completed sessions.

The trigger for splitting one out: FSE.md exceeds ~15KB, or a single domain (UI, schema, packages) accumulates enough rules to warrant its own focused reference. Until then, that content lives in FSE.md and that's correct — premature splitting fragments context as badly as bloat does.

Two of these carry strict promotion gates worth calling out:

FSE_POLICE.md — a rule lands here only after a real incident. Not speculatively, not "this might bite us." After it actually bit. The file is institutional memory of pain, not a wishlist of caution.

PATTERNS.md — a pattern earns its place only after it has shipped in a completed session. A clever idea you haven't used yet belongs in a session note, not in PATTERNS. The gate is "this worked in production at least once," not "this seems reusable."

Tier 3 — situational. Specific needs only.

BUILD_LOG.md files for complex multi-file sessions. AUDIT_REPORT.md when onboarding a legacy project. CHANGELOG.md, CONTRIBUTING.md, COLLABORATION.md — created when the specific situation calls for them and not before.

The principle underneath all three tiers

Start at Tier 1. Add a file only when the project's actual complexity demands it — a measured threshold (15KB), an accumulation of domain rules, or a concrete situation. Never create a file because the methodology "has" it.

The reason is the same reason FSE exists at all: a document the AI reads at every session start has to be true. A file created prematurely fills with speculative or aspirational content, drifts from reality as the code moves, and then actively misleads every session that reads it. An empty or absent file is honest about knowing nothing. A bloated, stale file lies. The tiering is a discipline against that lie — each file appears only when there's enough real content to justify it, so it's load-bearing from the day it's born.

Where it lives

The full document ecosystem and the tiering rules are in fse-core, now at methodology version 1.0.0: github.com/Joticle/fse-core

If you've run a project that outgrew Tier 1 — where you felt FSE.md getting heavy and split something out — when you made that call, and whether it helped, is a useful field report.