| name | source-annotation |
| description | Rules and procedural steps for adding @implements and @verifies traceability annotations to source code and test files. Use when writing new source files, adding test functions, or auditing existing code for missing traceability.
|
| triggers | ["add traceability annotation","annotate source file","add @implements","add @verifies","source traceability","code header traceability","missing traceability annotation"] |
| tools | ["read","search","edit"] |
Skill: Source Annotation
Purpose
Every production source file and test file must reference the GitHub Issues it implements or verifies. This creates bidirectional traceability from code back to requirements.
Required Annotation Forms
All four forms are valid and must be recognized by scanners:
Orphan annotations (missing #N) must fail CI scanner:
Production File Header (Required)
Every source module must have a top-of-file annotation block.
Python:
"""
<Module description>
Implements: #45 REQ-F-AUTH-001: User Login
Implements: #46 REQ-NF-SECU-002: Session Security
Architecture: #78 ADR-SECU-001: JWT Authentication
See: https://github.com/<owner>/<repo>/issues/45
"""
TypeScript/JavaScript:
C/C++:
Test File Annotation (Required)
Every test function must reference the requirement it verifies.
Python:
"""
Verifies: #45 REQ-F-AUTH-001: User Login
"""
def test_login_success():
"""
Verifies: #45 REQ-F-AUTH-001
Scenario: Given valid credentials → auth token returned
"""
...
TypeScript (Jest):
describe('User Login', () => {
it('should authenticate with valid credentials', async () => {
...
});
});
Procedural Steps
Adding annotations to a new source file
- Identify the REQ issues (from the IMP or design task) this file implements.
- Add
@implements #N REQ-ID at the top of the file for each requirement.
- If the file is a test file, use
@verifies instead of @implements.
- For HIL fixture-backed tests, also add
# Fixture source: PROBE #N.
Auditing an existing file for missing annotations
- Run
grep -rn "@implements\|@verifies\|Implements:\|Verifies:" <path> to find annotated files.
- For files with no annotation, identify the relevant requirement from git blame, PR history, or issue tracker.
- Add the annotation. If no requirement exists, create one before annotating.
- Verify that every
@implements REQ-ID and @verifies REQ-ID includes #N.
Detecting orphan annotations
An annotation is an orphan if it has a REQ ID but no #N. These must be resolved:
grep -rn "@implements REQ-\|@verifies REQ-" src/ tests/ | grep -v "#[0-9]"
Any match is a CI failure. Fix by adding the issue number.
Acceptance Criteria
References
