Instructions, skills, and the map

Teach your agent something, have it write the lesson into your project, and every later session starts out knowing it. You don't have to explain it again next week, or to a different agent.

A lesson left in one conversation doesn't reach the next session, which may make the same mistake again. So your project keeps its lessons in ordinary files beside the code: instructions hold the rules every session needs, skills hold methods for particular jobs, and the map explains how the project works. Your agents write and maintain these files, so each task leaves the next one better informed.

Say people use your app to save articles to read later, and on a train you find that saved lists won't open offline. Your agent fixes that and adds a test that opens a saved list with the network off. Then you ask:

"Make sure future agents know saved lists have to open without an internet connection, and why."

Your agent writes the rule into the project instructions and the reason into the mapMap↗Your project's own guide to how its software works and why, which your agents write and keep current.. The next session reads the rule first and finds the reason when it needs it, without the story of your train ride. The test catches a change that breaks offline reading, and the rule tells later agents why the test matters.

A rule such as "saved lists must open offline" belongs in the project instructions, discern/instructions.md by default. discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. writes your rules, with its own built-in instructions, into the file each coding agent reads, such as AGENTS.md or CLAUDE.md. So every agent gets the same rules, even after you switch agents.

Every session reads the instructions in full when it starts, so keep each rule short, with the longer reasoning in the map. Write project instructions shows how to add one.

Say you've found a good way to review a new screen: try each of its states, such as empty, loading, and failed, and check that people can tell what happened and what to do next.

A skill holds a method like that. Your agent sees only its short description until a job calls for it, then reads the full steps.

discern ships skills for jobs such as fixing a bug for good or splitting big work into tasks. Your project can add its own or adapt discern's, as Create and manage skills shows. Write each skillSkill↗A ready-made playbook that tells your agent how to handle a particular kind of task. to stand on its own, because "review it like last time" sends the next session looking for a conversation it can't see.

The map is your project's own guide, in discern/map/ by default, and your agents keep it current. For saved lists, it might explain where the app keeps them, what uses them, and why offline reading matters. Each point links to the code and tests behind it.

Reading the map shows you what your agents understand, so you can correct a misunderstanding before it turns into code. Ask:

"What does the project's guide say about saved lists? Does it still match the app after this change?"

Before a change can finish, discern checks the map's links and command examples and points your agent to the pages that link to the code the change touched. None of that proves a page is true, so your agent still checks each explanation against the code. Maintain the project map shows how to review a page.

Say you decide people can keep a reading list without an account, even though that limits syncing between devices. An Architecture Decision Record, or ADR, keeps what you decided, why, and the cost you accepted. A later agent then understands the choice before it proposes undoing it. Your agent writes one for a choice that's hard to reverse, surprising without context, and a real trade-off. An ADR only records a decision, so it can't excuse an agent from a requirement you've agreed to.

You don't need to know where each thing goes. Ask your agent to "capture this lesson", and it picks the smallest home that fits, updating an existing one instead of adding another.

A measurable gain, such as a smaller download, belongs in a standard, so ask for that one directly.

Your agent also offers to capture a lesson at a natural pause, such as after you correct it, and you decide what the project keeps.

Your project's README and its own docs stay yours. This manual explains discern itself, and discern's own map shows what a map looks like.