Documentation

Discover

Ask the customer about its goals, systems, rules and processes, and write the answers in one discovery document that every later stage uses.

Find out what the customer needs before you change a setting. Write the answers in one document, the discovery document. Every later stage uses it, and the handover note refers back to it.

Who to talk to

  • The person who decides for the customer and will own the organisation in CoRoid.
  • An engineering lead for each repository that CoRoid will work in.
  • The people who review and merge pull requests today.
  • Security or compliance, when the customer has rules about data, models or approvals.
  • The owner of each business process that a workflow will cover.

Questions to ask

Ask about outcomes and worries, not about settings. A customer says "nobody changes payment code without a review". You find the setting later.

Goals

  • What must be different after 90 days? Ask for a measure and its value today, for example "bugs that support reports are fixed within a week".
  • Which work must CoRoid do first? Which work must it never do?
  • Who asks for work today? Who will ask CoRoid for work?

Systems

  • Which git host and which repositories? Can CoRoid reach the git host over the public internet?
  • How does each repository build and run its tests? Which services do the tests need?
  • How do people sign in today? Does the company use an identity provider with SSO?
  • Which chat tool does the team use?
  • Where does work come from today: an issue tracker, an error tracker, a support inbox, a monitoring tool?
  • Which internal systems must agents read or change? Is there an MCP server for them?
  • How does code get to production? Who deploys, and on which days?

Rules

  • Where must the data stay? Must calls to AI models stay in the EU?
  • Which model providers are allowed? Does the customer have its own contracts and keys with model providers?
  • Which code needs the approval of a named person before it merges? Who approves?
  • What must every change pass: tests, coverage, security scans, translations?
  • What may CoRoid start without a person? How much may it spend per week or month?
  • What must the audit trail record, and for how long must it be kept?

Processes

  • Which business processes can a workflow cover? For each one: how does a case start, what are the steps, and which decisions need a person?
  • Which rules decide the rest? Write them as rows: "when this, then that".
  • What must happen when something breaks, for example a failed task or a failed deployment?
  • Which work must run on a schedule, for example a weekly clean-up?

People

  • Who are the owners and the admins? Who asks for work, and who only reviews?
  • Who maintains the setup after the handover?

The discovery document

Keep the document short. Use these sections, in this order.

  1. Goals. The outcomes for day 90, each with a measure and its value today.
  2. Systems. The git host and repositories, sign-in, chat, issue and error trackers, internal tools, and the way to production.
  3. Rules. Where data stays, allowed models, approvals, the checks that every change must pass, budgets, audit and retention.
  4. Processes to cover. For each project and each workflow: what it covers, who owns it, and how you know that it works.
  5. People. Each person's role in CoRoid, and who maintains the setup after the handover.
  6. Open questions. What the customer must still decide, and by when.

For each rule, write where it will be set. Configure lists every place. A rule that no setting covers is a request to CoRoid. See A need that nothing covers.

Done when

The customer reads the document and agrees with it. From then on, a change of plan goes into the document first, and then into the settings.