Audit Before You Build
Type: Open-source — client-agnostic methodology, no project-specific detail.
Created by akbarsha — https://github.com/iamakbarsha1
Distilled from cases where a checklist item was already ~90% shipped as a side
effect, and where "all issues closed" hid whole unbuilt layers — building from
the tracker text would have duplicated working code or missed real gaps.
Licence: Released under CC BY 4.0 — share and adapt for any purpose with
credit. Full text: LICENSE at the repository root.
Feedback & Support: If a rule here proves wrong or needs sharpening,
open an issue on the repository or contact the author at the profile link
above. If the problem is the agent not following a rule below rather than
the rule itself, that's an execution failure — acknowledge and correct it.
The core rule
A ticket, checklist, or spec line records a conversation about intent — it is
not a reliable record of what has or hasn't been built. Code drifts from the
tracker in both directions: features ship as side effects of other work
without their item being ticked, and closed items leave real layers unbuilt.
So the first step of "build X" is never design — it's an existence check. Grep
the codebase for the item's key nouns, cross-check the spec's own status
markers, and only then decide whether the task is "build", "finish", or
"verify and close".
Checks
- Grep for the item's key nouns before designing. Take the concrete terms
from the task — paths, function names, table/column names, endpoint routes,
spec keywords — and grep for each. Existing hits mean the work is partly or
wholly done. (A milestone item was ~90% already implemented as a side
effect of an earlier change; grepping the feature's route name surfaced it
immediately, turning a "build" into a small gap-closing task.)
- Cross-check the tracker against code and spec status, both ways. "Closed"
does not mean "built" and "open" does not mean "absent". Read the spec's own
Status headers and the code stubs together. (Illustrative: An "all issues closed"
milestone hid two entire layers that were never implemented — the tracker
said done, the code said empty.)
- Pivot the verb when reality disagrees. If the audit shows the thing
exists, restate the task honestly — "verify the existing X and close gaps A
and B" instead of "build X" — and say so before writing code. Duplicating
working code is worse than a slow start. (Illustrative: A ticket read "build the CSV
export endpoint"; the audit found a working export handler behind a feature
flag, so the task was restated as "flip the flag and add the missing
filename sanitization" before any code was written.)
Pre-flight check — before you write implementation code from a task
If any box is unchecked, you're building on the tracker's word — go audit the
code first.
1---2name: audit-before-you-build3description: Use as the FIRST step of any implementation task handed to you from a checklist, ticket, milestone, or spec — the first step is an existence check, not a design. Trackers record conversations, not deliverables, so grep for the item's key nouns and cross-check spec status before writing code, then pivot "build X" to "verify X and close the gaps" when it already exists. Triggers on "implement this ticket", "build feature X", "next milestone item", "from the checklist", "start this task", "add X".4---56# Audit Before You Build78**Type:** Open-source — client-agnostic methodology, no project-specific detail.910**Created by akbarsha — https://github.com/iamakbarsha1**1112Distilled from cases where a checklist item was already ~90% shipped as a side13effect, and where "all issues closed" hid whole unbuilt layers — building from14the tracker text would have duplicated working code or missed real gaps.1516**Licence:** Released under CC BY 4.0 — share and adapt for any purpose with17credit. Full text: `LICENSE` at the repository root.1819**Feedback & Support:** If a rule here proves wrong or needs sharpening,20open an issue on the repository or contact the author at the profile link21above. If the problem is the agent not following a rule below rather than22the rule itself, that's an execution failure — acknowledge and correct it.2324## The core rule2526A ticket, checklist, or spec line records a conversation about intent — it is27not a reliable record of what has or hasn't been built. Code drifts from the28tracker in both directions: features ship as side effects of other work29without their item being ticked, and closed items leave real layers unbuilt.30So the first step of "build X" is never design — it's an existence check. Grep31the codebase for the item's key nouns, cross-check the spec's own status32markers, and only then decide whether the task is "build", "finish", or33"verify and close".3435## Checks3637- **Grep for the item's key nouns before designing.** Take the concrete terms38 from the task — paths, function names, table/column names, endpoint routes,39 spec keywords — and grep for each. Existing hits mean the work is partly or40 wholly done. *(A milestone item was ~90% already implemented as a side41 effect of an earlier change; grepping the feature's route name surfaced it42 immediately, turning a "build" into a small gap-closing task.)*43- **Cross-check the tracker against code and spec status, both ways.** "Closed"44 does not mean "built" and "open" does not mean "absent". Read the spec's own45 Status headers and the code stubs together. *(Illustrative: An "all issues closed"46 milestone hid two entire layers that were never implemented — the tracker47 said done, the code said empty.)*48- **Pivot the verb when reality disagrees.** If the audit shows the thing49 exists, restate the task honestly — "verify the existing X and close gaps A50 and B" instead of "build X" — and say so before writing code. Duplicating51 working code is worse than a slow start. *(Illustrative: A ticket read "build the CSV52 export endpoint"; the audit found a working export handler behind a feature53 flag, so the task was restated as "flip the flag and add the missing54 filename sanitization" before any code was written.)*5556## Pre-flight check — before you write implementation code from a task5758- [ ] You grepped the codebase for the task's key nouns (paths, names, spec59 terms) and know what already exists.60- [ ] You cross-checked tracker status against actual code AND spec status61 markers, not just the ticket text.62- [ ] If the thing partly exists, you restated the task as verify/finish and63 said so before building.6465If any box is unchecked, you're building on the tracker's word — go audit the66code first.
iamakbarsha1