ax-annotation

@AX Annotation Skill

The canonical @AX rule set is emitted into this skill by the harness generator, so the tag definitions, trigger conditions, lifecycle rules, and per-file limits below are authoritative for this installation. This skill provides actionable guidance for WHEN and HOW agents apply @AX tags.

Canonical Source

Do NOT redefine tag rules elsewhere. Treat the sections of this document as the single source and apply them as written.

When to Apply @AX Tags

NOTE Triggers

Apply @AX:NOTE when you encounter:

• A magic constant with no explanation
• An exported function over 100 lines that has no godoc comment
• A business rule that is not self-evident from the code

WARN Triggers

Apply @AX:WARN (with @AX:REASON) when you detect:

• A goroutine or channel launched without a context.Context
• Cyclomatic complexity >= 15 (check with gocyclo or manual count)
• Mutation of a package-level or global variable
• A function with 8 or more if branches

ANCHOR Triggers

Apply @AX:ANCHOR (with @AX:REASON) when:

• A function has fan_in >= 3 callers (heuristic: grep -r "FuncName(" . | wc -l)
• Removing or renaming the symbol would break multiple consumers

TODO Triggers

Apply @AX:TODO when:

• A public function has no corresponding test file
• A SPEC requirement is referenced but not yet implemented
• An error is returned without handling (silent discard)

Application Workflow

Execute after the GREEN or REFACTOR phase of TDD:

1. Scan — list all files modified in this task
2. Detect triggers — for each file, check NOTE / WARN / ANCHOR / TODO conditions above
3. Draft tags — prefix every agent-generated tag with [AUTO]
4. Attach REASON — add @AX:REASON immediately after every WARN and ANCHOR tag
5. Count per-file — verify ANCHOR <= 3 and WARN <= 5 per file
6. Handle overflow — apply overflow strategy (see below)
7. Commit — include tags in the same commit as the code change

Per-File Limits and Overflow