Skip to content

Write a how-it-works document

Apply this procedure to the module named by the knowledge task. Read the task/version; the coordinator runs the local delivery with scripts/heyaira-run.sh.

1. Pin the implementation and evidence

  1. Record repository, reviewed commit, module and relevant merged PR or RESULT references.
  2. Read changed code and tests before reading the design specification as a comparison.
  3. Follow imports/callers to locate entry points, actors, persistent state and emitted results.
  4. Read the latest relevant RESULT notes; retain their test limitations and commit references.
  5. Check the running revision through server_identity only when making deployment claims.
  6. Label differences between reviewed code and the running revision; do not imply deployment.

Use these reads to locate the implementation and obtain line references.

git rev-parse HEAD
git show --stat <merged-commit>
rg -n '<entry-point|state|tool-name>' src tests docs
nl -ba <source-file> | sed -n '<first>,<last>p'

2. Draft a document below 250 lines

  1. Use the project's documentation language; HeyAira repository docs use English unless the task specifies Polish.
  2. Keep the labels Źródła and Rozjazdy visible; write the body in the selected language.
  3. State purpose in two sentences: the trigger and the observable result.
  4. Define actors by what they read/write on this path, not by copying role profiles.
  5. Describe the actual execution order, including refusals and recovery paths that exist in code.
  6. Prefer tables for actors, steps, state transitions, fields and branch conditions.
  7. Use prose only to explain a dependency or condition that the tables cannot express clearly.
  8. Omit proposed functionality; name missing behavior in Rozjazdy if it matters to the comparison.

Use this outline; keep headings empty only while drafting, never at delivery.

# <Module>: how it works / Jak działa
Reviewed: <repository>@<commit>; verified: <date>; runtime: <revision|unverified>
## Purpose / Cel
## Actors / Uczestnicy
| Actor | Input | Allowed effect | Boundary |
## Path / Przebieg
| Step | Trigger/condition | Code action | State/output | Refusal |
## State and contracts / Stan i kontrakty
| State/field | Writer | Reader | Constraint |
## Checks and limits / Sprawdzenie i ograniczenia
## Rozjazdy
| ID | Document claim | Code observation | Evidence pair | Next actor |
## Źródła
- <file:line> — <claim supported>; reviewed at <commit>
  1. Add repository-relative file:line references to implementation and meaningful tests.
  2. Pin the reviewed commit in the document header; regenerate line references after source movement.
  3. Check each reference points to the stated symbol/condition, not just an existing file.
  4. State actual test commands/results from receipts or your own permitted checks; identify which source supplied them.
  5. Separate completed, simulated, skipped and unverified behavior in the checks section.
  6. Use specifications as the claim side of a comparison, never as proof the feature exists.
  7. Do not paste handoffs, memory bodies or conversation transcripts into the document.

4. Record and route drift

  1. Compare current module docs/specs against the pinned implementation after the merged change.
  2. For each mismatch, record both the document location and the code/test location.
  3. Give each row a stable ID and observable consequence; avoid architecture recommendations as facts.
  4. Mark an inaccessible live/public document unverified; compare its committed publishing source instead.
  5. Report drift IDs and proposed repair acceptance checks to the coordinator through RESULT.
  6. Ask the coordinator to create follow-up tasks when the execution token cannot create tasks.
  7. Write None observed in the reviewed scope only after the comparison; keep unreviewed areas explicit.
  8. Update process-map/day-report references only if the frozen task includes those paths.
  9. Do not change module code, roles or architecture to make the description easier to write.
  10. Send no unsolicited owner report from a knowledge task; route findings to the coordinator.

5. Check the deliverable

  1. Run wc -l <document>; keep the result under 250 without deleting necessary evidence.
  2. Run git diff --check and inspect every changed path against the authorized documentation scope.
  3. Check local links and at least five source claims against the pinned files.
  4. Run the documentation checks named by the task; keep their real output in authorized evidence.
  5. Return source SHA, document path, drift IDs, checks and limitations in RESULT/receipt.

Sources