Goals and notes

A project needs two pieces of writing before its tickets can be any good: a goal that says where the current phase is going, and notes that say what should shape the work on the way there. Both live on the project, both are shown to the people working on it, and agents read both every time they work on one of its tickets.

This page explains how to write each one well. It belongs to the Define job described in How we deliver.

#The project goal

The Goal field is on the project form and is shown at the top of the project page. It describes the end state the current phase is working toward.

Write it so that someone who was not in the room could check whether it is true. That usually means describing what a user can do, or what is measured, once the phase is finished. A goal that cannot be checked turns into an argument at the end of the phase about whether it was met.

#Good and weak goals

Weak	Better
Improve the checkout.	A returning customer can pay with a saved card in two steps, and checkout abandonment is below 60% for a full month.
Modernise the platform.	The storefront runs on a supported framework release, every page passes the existing tests, and nothing on the old release is live.
Build the reporting module.	An account manager can export a client's monthly hours as a spreadsheet the client accepts without edits.

The weak versions are not wrong, they are just impossible to finish. The better versions name a person, an action and a way to tell.

#Tips

• One phase, one goal. When the phase changes, rewrite the goal. If an old goal still explains something, keep it as a decision note.
• Keep it short. Two or three sentences. If it needs a page, part of it is probably an outcome.
• Say what, not how. "Customers can pay with a saved card" is a goal. "Integrate the payment provider's card vault" is a ticket.
• Revisit it when outcomes are added. If an outcome does not move the project toward the goal, either the outcome or the goal is wrong. The outcome checks ask exactly that.

#Notes

Notes live on the project's Specs & notes tab, next to the tech specs. Each note has a title, a category and a body. Agents read all of them, so a note is the most direct way to tell every future agent and reviewer something once.

There are four note categories. They sit alongside the spec categories (stack, architecture, api, database, infra, integration, security, other), which describe the system itself.

Category	What it holds	Example
context	Background facts someone new would need.	The client runs a wholesale business; most orders are placed by staff on behalf of customers.
constraint	Something that must stay true.	Order totals must match the accounting system to the cent. Never round before tax is applied.
guidance	How we prefer things done here.	Keep validation out of the controllers. Name new tables the way the existing ones are named.
decision	A choice that was made, and why.	Prices are stored in whole cents. Chosen in March after a rounding bug in the old system cost a week.

#Writing notes that help

• One idea per note. A note titled "Things to know" with twelve bullet points is hard to update and easy to ignore. Twelve short notes are better.
• Give the reason. A constraint without a reason gets broken by someone who thinks it no longer applies. A decision without its reason gets reopened.
• Write for a stranger. The reader might be a new developer, a reviewer from another team, or an agent that has never seen the project. Avoid nicknames and shorthand.
• Prefer specific to general. "Use the existing money helper for any amount" is more useful than "be careful with money".
• Delete what is no longer true. A stale note is worse than a missing one, because the agent will follow it.

#Context, constraint, guidance or decision?

If you are unsure which category a note belongs in, ask what happens if it is ignored.

• If ignoring it means the agent misunderstands the problem, it is context.
• If ignoring it breaks something, it is a constraint.
• If ignoring it produces working code that the team would ask to be changed in review, it is guidance.
• If ignoring it reopens a question that was already settled, it is a decision.

#How agents use them

When an agent picks up a ticket, it is given the project goal, the ticket's outcome, the tech specs and every note, each note with its title and category. If the project works together with other repositories, their specs and notes come too. See What an agent reads.

The run screen shows everything the agent was given. If an agent did something surprising, that is the first place to look: check whether the goal and notes said what you thought they said.

Notes and specs apply to the whole project. For something only one ticket needs, write it in the ticket's description, its acceptance criteria, or the instruction when you assign the agent. For something an agent should know on every project, add it to that agent's knowledge. See AI coding agents.

#Keeping them current

Goals and notes drift if nobody owns them. A simple habit works: when a review uncovers something that should have been known up front, add it as a note before closing the ticket. When a decision changes, edit the decision note rather than adding a second one that contradicts it.

Next: Outcomes and quality checks.