Decisions and memory

These commands record what you decided and how you build, so your agent does not reopen settled questions. Decisions and examples go into the project's agent context the next time you run intentdocs sync --context. All of them need a connected checkout.

intentdocs decide

Logs an architectural or product decision.

intentdocs decide [title] [options]

intentdocs decide "Use row-level security for tenancy" \
  --description "Harder to bypass than a filter in application code" \
  --category architecture

Both a title and a description are required. If either is empty, the command prints Title and description required. and logs nothing.

Behaviour to know:

• --story is looked up first, the same way show and done find a story. When nothing matches, the command logs nothing and exits 1.
• A category outside the four listed also fails to save.
• A first word of list, amend, delete or retract runs that subcommand. To log a decision whose title starts with one of those words, run intentdocs decide with no title and type it at the prompt.
• intentdocs done also offers to log a decision, linked to the story you just finished.

intentdocs decide list

Lists logged decisions.

intentdocs decide list

Each line shows the first eight characters of the decision's ID, its category and its title. Retracted decisions are marked (retracted).

  8c41d0f2  [architecture]  Use row-level security for tenancy
  1a7e93bb  [technical]  Queue emails instead of sending inline (retracted)

intentdocs decide amend

Changes a decision's title, description or category.

intentdocs decide amend <id> [options]

intentdocs decide amend 8c41 --category trade-off

With no options, it prompts for a new title and description; leave either blank to keep it. Without a terminal to answer, it exits 1 and asks you to pass an option. It exits 1 when no decision matches, or when the decision has been retracted.

intentdocs decide delete

Retracts a decision. intentdocs decide retract is the same command.

intentdocs decide delete <id> [options]

intentdocs decide retract 1a7e --reason "We moved to a managed queue"

It shows the decision and asks you to confirm. A retracted decision is kept and marked, not removed, and the change is audited. You cannot amend it afterwards.

Without a terminal to answer, it refuses and exits 1 unless you pass --yes. Piped input never counts as confirmation.

intentdocs note

Adds a note to a story.

intentdocs note <storyId> [note]

intentdocs note PB-42 "The redirect bug was a stale cookie domain, not the token"

The note is added to the end of the story's notes on the server, after a blank line. Earlier notes are kept. This is the same as the add_note MCP tool. If .intent/stories/<id>.md exists, the note is also added, with a timestamp, under that file's Implementation notes section, which intentdocs done attaches to the story when you finish.

intentdocs example

Adds a before/after code example to the project, for your agent to follow.

intentdocs example

No arguments or options. It prompts for:

• Title. Required; an empty title exits 1.
• Description. Optional.
• Language. One of typescript, javascript, python, bash, sql or other. Anything else, or an empty answer, becomes typescript.
• Before code and after code. Paste the code, then enter an empty line to finish each block. An empty line inside your code ends the block early.

It saves the example and reminds you to run intentdocs sync --context so the example reaches your agent's context file. It exits 1 when the save fails.