| name | code-annotate |
| description | Generate boilerplate `# implements:` annotation for a function based on the artefact ID, inserting it as the first line of the function body. |
Skill: code-annotate
Use this skill when adding implementation code that satisfies a REQ or DES. Generates the correct # implements: annotation, validates that the cited IDs exist in the registry, and inserts the annotation in a syntactically-correct place.
Inputs
<artefact-id> — the REQ or DES being implemented (e.g., REQ-auth-001, DES-auth-001, or P1.SP2.M3.REQ-007)- File path and function name (from active editing context)
Steps
-
Verify the artefact exists. Read library/_ids.md; confirm <artefact-id> is declared.
-
Detect the language. Python (#), JavaScript/TypeScript (//), Go (//), Rust (//). Default # if unknown.
-
Determine the comment line. Choose the comment syntax matching the file extension.
-
Insert the annotation. Place <comment-prefix> implements: <artefact-id> as the first line of the function body, immediately after the opening brace / : / func ... {.
-
Confirm. Show the diff to the user.
-
Run annotation_format_integrity on the file to verify the annotation parses correctly.
Annotation placement rules
<!-- implements: <DES-ID> --> and # implements: <DES-ID> annotations ALWAYS go on the implementing artefact:
- A Python function body — first line of the body, comment form
- A SKILL.md file — immediately after frontmatter close
---, HTML-comment form
- A governance document — YAML frontmatter
satisfies_by_existence: [...] or implements: [...]
NEVER place annotations:
- Inside a design-spec.md DES element (the DES is what is satisfied, not what implements)
- Inside a requirements-spec.md REQ element
- Inside a test-spec.md TEST element
The spec layer expresses obligation; the implementing artefact carries evidence. Crossing the layers blurs the audit trail.
Done criteria
- Annotation inserted in syntactically-correct location.
- annotation_format_integrity passes.
- One commit with the annotation; the implementing code is the user's responsibility.
