Skip to content
Komputa Practice
Esc
↑↓navigate↵open⌘Jpreview
On this page

Build a change

Take a bug fix or a small feature from the prompt to the merge, with the checks that its risk needs.

Use this guide for one pull request: a bug fix, a small feature, a refactor or a docs change. For work that needs many pull requests, use Run large work as a program.

Before you start

Steps

  1. Ask for the change and its checks. Say what must be true when it is done. For example:

    Fix the rounding of the invoice total: a line of 3 at 33p must total 99p.
Open a pull request when it is done.

  2. Read the tier. The agent puts the change in a tier and says why. The tier sets the process:

    Tier When Checks
    1. Change A fix, docs, a refactor: nothing a user sees changes The tests that cover it, one run of the real behaviour, and you read the diff
    2. Feature A change that a user sees A short plan with acceptance checks, and a verifier subagent that runs them
    3. High risk Security, money, private content, data that cannot be restored, a service others depend on Tier 2, plus one test for each high risk and one adversarial review on another model

    If the tier looks wrong, say so now. The tier follows the risk, not the size.

  3. Let it build. The agent writes the tests that the risk needs: the domain rules, the happy path, and one failure case for each high risk. A fix for a defect that a user hit carries one test that fails before the fix and passes after it. It runs the gate while it works:

    scripts/gate.sh          # the sections that the change touches
scripts/gate.sh --full   # everything, before the pull request

  4. Read the report. The agent opens the pull request and reports the commands it ran and what they printed. For tier 2 and up, the report includes what the verifier ran and found.

  5. Merge when every check passed on the last commit. Check that CI ran on the pull request’s head commit, then merge that commit:

    gh pr checks <number>
gh pr merge <number> --merge --match-head-commit <full head sha>

Check it worked

  • CI passed on the head commit of the pull request.
  • The report names a run of the real behaviour and its output, not only “tests pass”.

What can go wrong

  • A hook refuses a command. The agent sees a line that starts with BLOCKED: and says what the hook allows instead. For example, the only forced push allowed is a lease with the exact SHA, on a branch that is not the default. Do not turn the hook off.
  • The agent wants to delete or skip a test to get green. The rules forbid it. The fix goes in the code, or in a test that was wrong.
  • The agent finds other work on the way. It files that work as a separate issue and keeps the pull request to what you asked for.
  • The gate fails on its time budget. The message names the slowest step. A budget rises only with a reason in gate_budget_reason in .copier-answers.yml.

Next steps

Was this page helpful?