Maintain the project map

A new agent should be able to find where a feature belongs and what a change must preserve. The mapMap↗The project's account of how its software works and why. gives them that starting point. It also gives you a readable account of what your agents understand, so you can correct a mistaken assumption before it becomes code.

Once discerndiscern↗A tool that installs and runs an agent development practice in a project. is set up, your agent maintains the map alongside the project. You can ask for a focused review:

Check the map's explanation of saved lists against the current code and tests. Update what is wrong, and show me the constraint a future change must preserve.

Your agent searches the map in the language of the task, reads the relevant region's README, and follows its links to the implementation, tests, configuration, and decisions. Existing project documentation can remain the authority; the map links to it and explains why it matters.

The agent checks the claims that the change could affect. Each page explains how the project works now, in the present tense. The agent replaces obsolete descriptions and removes stories about resolved bugs or completed changes. A current page needs no cosmetic edit. If the evidence is missing or conflicts with an agreed requirement, the agent reports the gap instead of writing a confident claim. You decide unresolved product intent; the project’s work ledger holds concrete unfinished work.

A useful page connects behavior, boundaries, and constraints. A short implementation summary can make that connection clear. Naming every method usually does not.

For example, “parse reads the file, validate checks it, write saves it” gives a reader little help. “Validation completes before the saved file is replaced, so failed validation preserves the previous usable copy” explains something a future change must preserve. The page links to the implementation and the failure tests so the reader can check that account.

Requirements and observed behavior can differ. “Saved lists must work offline” records agreed intent. The agent checks the implementation before claiming that offline reading works today. An ADR can preserve the reason for the requirement; a test can cover its behavior.

Setup provides a complete starting map, sized to what the project actually contains. The root explains the project and routes readers to orientation, real subsystem responsibilities, development practices, and decisions. Short topics can share a region README. Numbered folder names are an optional reading order.

When a feature grows, the agent first updates the nearest relevant section. A distinct reader task can earn a child page. A new responsibility with a lasting boundary can earn its own region and README. This keeps ordinary feature additions near the systems they affect.

A project with no implementation yet still benefits from an agreed direction. Setup writes a design-principles page that explains the rules you choose, why they matter, and how they guide future work. It also provides a gateGate↗The configured checks a change must satisfy for ordinary completion.-gotchas page with recovery advice that agents build on when they solve a new failure. As responsibilities emerge, the agent groups their explanations into regions.

The map explains how the project's parts fit together and links to the authorities needed for a change. Instructions carry standing rules; skills carry repeatable methods; checks verify behavior; checkpoints ask for judgment; ADRs preserve the reasoning behind significant architectural choices; the work ledger records open work.

A subsystem page might connect a data boundary to its tests, the approved decision behind it, and a recovery procedure. It need not copy those sources. The questionsQuestion↗Something the agent is asked to judge about the project or a change. worth preserving depend on the project: data handling, failure recovery, compatibility, or release dependencies may matter without needing a separate page for each.

For a large documentation effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to., the agent can use the existing delegation workflow with ordinary task briefs. Projects can keep their own editorial instructions or skills when they need a particular house style.

A map needs ordinary Markdown; frontmatter is optional. A project can keep current supporting material under _internal, where agents can search and read it. Those pages receive the same integrity checks as other current map pages.

Decision records under _adr preserve history and can be opened by their target. _private stays outside default discovery; an explicit target can retrieve it. Neither name provides access control over the repository. Other underscore folder names do not make a page historical or exempt from current-page checks.

Publication is a separate choice. Filtered exports still respect publication metadata and their selected scopeScope↗A named set of project paths used to select work or policy.. discern's own manual and public map directory have their own publication rules; your local map does not inherit the manual's frontmatter requirements.

The map links each explanation to files that support it. When those files change, the map browser can point your coding agent to pages worth reviewing. It compares each page with its own saved history. Editing another page does not clear that signal. Without file links or usable history, freshness is unknown.

The map checkpoints ask the coding agent to review new explanations, substantial rewrites, and pages linked to changed sources. A wider change can prompt review even without those links. These checks guide attention; they cannot judge whether a page is true. If an explanation still matches the project, it needs no edit.

The finished change gives a new reader a useful explanation, evidence links, and a route from the map root to the affected pages. The agent checks factual claims as well as navigation. discern's mechanical checks and freshness signals help locate problems; they cannot establish that an explanation is true.

You can ask the agent to walk through the page as a new contributor. If it leaves a reader unable to locate the relevant code or understand a consequential constraint, the explanation still needs work. Instructions, skills, and the map explains how the different kinds of project knowledge support the next session.