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

1. Verify the artefact exists. Read library/_ids.md; confirm <artefact-id> is declared.

2. Detect the language. Python (#), JavaScript/TypeScript (//), Go (//), Rust (//). Default # if unknown.

3. Determine the comment line. Choose the comment syntax matching the file extension.

4. Insert the annotation. Place <comment-prefix> implements: <artefact-id> as the first line of the function body, immediately after the opening brace / : / func ... {.

5. Confirm. Show the diff to the user.

6. 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.