Skip to content

refactor(aidd-context): citations are markdown links at their point of use - #569

Merged
blafourcade merged 2 commits into
nextfrom
refactor/skill-citation-rules
Jul 31, 2026
Merged

refactor(aidd-context): citations are markdown links at their point of use#569
blafourcade merged 2 commits into
nextfrom
refactor/skill-citation-rules

Conversation

@blafourcade

@blafourcade blafourcade commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

🎯 What & why

Two claims were reported against aidd-context:04-skill-generate: it never says to use markdown links, and never says to cite a reference at the point it is used. The first is half true, the second is true. Fixing the contract exposed that the rule was never applied outside the two skills a July migration touched, so 143 citations across six plugins still used a notation nothing reads.

🛠️ How it works

Commit 1 rewrites the contract. skill-authoring.md R6 covered only what an action cites from a reference, and said nothing about placement. It now covers assets too and requires a citation to sit where it is used, never gathered in a list of its own. R8 gains the counterpart it always implied: a reference names a sibling, never links it.

Three deliberate scope calls:

  • Placement is "where it is used", not "inside a ## Process step" — which is weaker than reported, on purpose. Three of skill-generate's own actions cite from ## Output or ## Test at their point of use (01-scope.md:19). The strict rule would make 04-validate flag its own source.
  • Scoped to actions, not the router. grep '](\.\|@' plugins/*/skills/*/SKILL.md returns nothing; the action table names slugs on purpose.
  • R2's naming.md stays in backticks. A global link rule would force a reference to link a sibling, which R8 forbids.

Commit 2 migrates the fleet. 7661980 converted skill-generate and project-memory only, as its own message states. Both are still at zero; nothing regressed. Everything else was never in scope and inherited nothing, because skill-authoring.md is local to 04-skill-generate.

143 citations, three shapes:

Shape Count Action
Inline `@../references/x.md` 133 converted one for one, surrounding punctuation kept, no sentence restructured
Bare @path alone in a fenced block 8 inlined into the step that consumes it, fence removed
@ as a literal character 1 untouched
A glob, @../assets/recipes/*.md 1 @ dropped, backticks kept — a glob is not a citation

The eight fenced ones were first carved out as "load mechanics". That was wrong: nothing parses them, a link inside a fence renders as literal text, and 02-upsert.md stacked three of them in a block above ## Input with no step naming any — the exact shape R6 now forbids.

Out of scope: @claude in the orchestrator routing regex and @playwright/mcp in a cook recipe. Neither is a citation.

Full reasoning and the counts behind each decision: proposal.md.

🧪 How to verify

  • grep -rn '@\.\.\?/' plugins/ → empty.
  • The markdown-links pre-commit hook passes: 0 broken in 561 files. The two pre-existing failures in plan-template.md are scaffold placeholders in an untouched asset.
  • Read 08-hook-generate/actions/02-write-hook.md before and after — four citations per step, now clickable.

⚠️ Heads-up

skill-authoring.md stays local to 04-skill-generate. The other generators (05-rule-generate, 06-agent-generate, 07-command-generate, 08-hook-generate) each carry their own *-authoring.md and inherit nothing, so R6 does not reach what they emit. This conversion holds until one of them generates the next skill. Propagating the contract is a separate subject, not folded in here.

✅ I certify

  • I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

blafourcade and others added 2 commits July 31, 2026 07:35
R6 mandated a markdown link only for what an action cites from a
reference, and said nothing about where the citation goes. Authors could
legally gather every reference in a block above the first step, which is
what several skills did.

R6 now covers everything an action cites, reference or asset alike, and
requires the citation to sit where it is used rather than in a list of
its own. The rule stays scoped to actions: no router in the repo cites a
path, and R8 forbids a reference from linking a sibling, so R8 now states
that counterpart instead of leaving it implicit.

Placement is deliberately "where it is used", not "inside a Process
step": three of skill-generate's own actions cite from Output or Test at
their point of use, and a stricter rule would make the contract flag its
own source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Commit 7661980 converted @-citations to markdown links in skill-generate
and project-memory only. Every other skill kept the @ form, so 143
citations across six plugins pointed at files with a notation nothing
reads: @path is inert in a skill body, resolving only in a CLAUDE.md
import. A markdown link is what an agent follows and what the
markdown-links pre-commit hook verifies, so a stale @ rots silently.

133 inline citations convert one for one, keeping their surrounding
punctuation so no sentence is restructured. Eight more sat alone inside a
fenced block; those are inlined into the step that consumes them, which
also removes the three references upsert stacked above its Input section.

Left alone: @ as a literal character in onboard's reserved-key list, the
glob in cook's list action (a glob is not a citation, so it just loses
the @), @claude in the orchestrator routing regex, and the npm scope in a
cook recipe. rule-generate's tool-paths named a sibling reference with a
@; per R8 a reference names, never links, so the @ is dropped and the
backticks stay.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@blafourcade
blafourcade marked this pull request as ready for review July 31, 2026 07:22
@blafourcade
blafourcade requested a review from a team as a code owner July 31, 2026 07:22
@blafourcade
blafourcade merged commit 5ee9da9 into next Jul 31, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant