agentleFS
opendatadiscoveryopendatadiscovery/odd-team/.claude/skills/enrich/SKILL.md

enrich

Skill0 starsChanged 2 months agoApache-2.0View on GitHub

Run the file-analyser subagent against one or more substrate nodes to produce per-node semantic enrichment sidecars. Resolves a path / node-id / batch spec to substrate nodes; spawns file-analyser per node; validates the resulting sidecar against the schema; updates the manifest's `enrichment` block.

6 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ingest and setup.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JaimeGBASkill

    ingest

    Digest an external source (article, paper, transcript, URL, book chapter) and integrate its content into the knowledge base

    Also in 3 projects that use this

  • VercelSkill

    setup

    Set up Vercel CLI and project configuration. Use when the user says "set up Vercel", "configure Vercel", "link to Vercel", or "vercel init".

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 4 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read these (skip if already loaded this session):

    line 32
  2. Distinctive:

    If the worklist is empty, report "Nothing to enrich (all nodes current)" and exit.

    line 47
  3. Very specific:

    Before spawning file-analyser for a node, check whether the sidecar is already current:

    line 69
  4. Very specific:

    If lineage/{repo}/understanding/{slug}.md does NOT exist → CACHE MISS, proceed to spawn.

    line 71
  5. Distinctive:

    If the sidecar exists, parse its frontmatter:

    line 72
  6. Very specific:

    Force re-enrichment: when the maintainer passes --no-cache or --force.

    line 81
  7. Very specific:

    Run the validator: python -m lineage_extractor.cli validate-sidecar <sidecar-path> (Bash).

    line 116
  8. Very specific:

    If validation fails, log the failure to lineage/{repo}/enrichment.log and surface to the maintainer.

    line 117
  9. Distinctive:

    After all nodes in the worklist complete (success or failure):

    line 121
  10. Very specific:

    Add or update the enrichment block:

    line 124
  11. Very specific:

    Live-URL-only doc rule is non-negotiable: If a sidecar has a documents.declared_docs entry without last_verified_status, validation fails.

    line 146
  12. Very specific:

    One sidecar per node: Don't enrich neighbour nodes in the same invocation — they get their own /enrich call when the maintainer chooses.

    line 147
  13. Very specific:

    Preserve ## Maintainer notes: If a sidecar already exists, pass its content as EXISTING_SIDECAR so the file-analyser preserves the …

    line 149

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Enrich an ontology node (DOC-164 slice 5+)

Drive the agentic-code-ontology pipeline for one or more substrate nodes. Each invocation produces (or refreshes) Markdown sidecars at lineage/{repo}/understanding/{slug}.md, written by the file-analyser subagent with the live-URL-only doc rule and Gate 9 code-anchor mandate.

This skill is the maintainer-facing entry point for the per-node enrichment layer per adrs/drafts/agentic-code-ontology.md revision 2.

Prerequisite

The substrate scaffold (DOC-164 slices 1-4) must have run against the target repo. lineage/{repo}/nodes.jsonl must exist. If it doesn't, run /scan scanners/code-lineage/{axis}.md first or invoke the substrate's lineage-extractor scan {repo} --full.

Argument forms

FormBehaviour
/enrich <path>Single-file enrichment. Resolves <path> (relative to a repo) to its substrate node(s) and enriches each. If the path matches multiple nodes (e.g. a controller file with multiple methods), enrich the file-level node first, then the maintainer can drill into method nodes via /enrich --node <id>.
/enrich --node <node-id>Single-node enrichment by node ID (verbatim from nodes.jsonl's id field).
/enrich --touchedPer-PR incremental. Reads lineage/{repo}/manifest.yaml's enrichment.last_enriched_commit; computes git diff against repo HEAD; enriches every node whose source file appears in the diff (1-hop fanout NOT YET — slice 5 is single-file granularity).
/enrich --batch <axis>Backfill mode. Picks the next N (default 5) unenriched-or-stale nodes from a given axis (ui_shell, ui_routes, controllers, openapi_tags, config_prefixes). Useful for working through the backlog one axis at a time.
/enrich --max-nodes NCap how many enrichments this session runs. Default 5 (fits comfortably in a session's context budget; tune empirically). Caps any of the above forms.

Protocol

1. Orient

Read these (skip if already loaded this session):

  • CLAUDE.md — the workspace's quality bar
  • adrs/drafts/agentic-code-ontology.md — the layered ADR + the per-node sidecar schema
  • .claude/agents/file-analyser.md — the subagent system prompt you'll invoke (so you know what input shape it expects)

2. Resolve the worklist

Build a list of (node_id, path, kind, axis) tuples for this invocation:

  • For <path> form: jq -c 'select(.path == "<path>" or (.path | startswith("<path>:")))' lineage/{repo}/nodes.jsonl. Pick the file-level match first; if multiple symbol-level nodes also match, list them but don't enrich them this invocation (one node at a time).
  • For --node <id>: jq -c 'select(.id == "<id>")' lineage/{repo}/nodes.jsonl. Exactly one match expected; error if 0 or >1.
  • For --touched: read lineage/{repo}/manifest.yaml's enrichment.last_enriched_commit (or last_scan_commit if no enrichment block yet). git -C ../{repo} diff --name-only <commit>..HEAD → list of touched files. For each touched file, jq for nodes whose path starts with that file. Cap at --max-nodes.
  • For --batch <axis>: jq -c 'select(.axis == "<axis>")' lineage/{repo}/nodes.jsonl → all nodes; filter out those with an existing lineage/{repo}/understanding/{slug}.md whose enriched_at_commit matches current HEAD; pick the first --max-nodes.

If the worklist is empty, report "Nothing to enrich (all nodes current)" and exit.

3. Resolve the sidecar slug for each node

Slug rule (matches the ADR): node_id.replace(' ', '__').replace('/', '_').replace(':', '__').replace('.', '_'). Filesystem-safe, reversible, greppable.

Sidecar path: lineage/{repo}/understanding/{slug}.md.

4. Resolve scaffold edges per node (1-hop)

For each node in the worklist, read lineage/{repo}/edges.jsonl and collect:

  • imports: edges where this node is src and type=imports
  • imported-by: edges where this node is dst and type=imports
  • exposes: src→dst with type=exposes
  • configures: src→dst with type=configures
  • mounts: src→dst with type=mounts

This goes into the file-analyser's prompt as SCAFFOLD_EDGES.

4.5. Cache check (slice 6+)

Before spawning file-analyser for a node, check whether the sidecar is already current:

  • If lineage/{repo}/understanding/{slug}.md does NOT exist → CACHE MISS, proceed to spawn.
  • If the sidecar exists, parse its frontmatter:
    • enriched_at_commit — substrate commit at which the sidecar was authored
    • prompt_version — the file-analyser prompt version that authored it
    • (planned: extracted_at_commit, model, scaffold_hash for finer cache keys)
  • Compare to the current substrate state (manifest's last_scan_commit) AND the current file-analyser prompt version (read the frontmatter of .claude/agents/file-analyser.md — typically file-analyser/0.1.0 for slice 5/6).
  • Skip the spawn IF:
    • enriched_at_commit == last_scan_commit (substrate hasn't moved)
    • prompt_version == current file-analyser version (prompt unchanged)
    • The node's source file hasn't changed since enriched_at_commit (use git -C ../{repo} log --oneline <enriched_at_commit>..HEAD -- <source_path> — empty output = unchanged)
  • Force re-enrichment when the maintainer passes --no-cache or --force. Default is cache-on; this is the cheap/fast path.

Cache hits are reported as <node-id>: cached (no change since <commit>). Cache misses fall through to the spawn step.

The cache invariant per the ADR: an enrichment is reused iff (node_id, scaffold_hash_of_file, prompt_version, model) matches. MVP slice-6 collapses this to (node_id, source_unchanged_since_enriched_at_commit, prompt_version) — the source-unchanged check is a proxy for scaffold_hash. Future slices may add explicit content-hash keys if false-cache-misses surface.

5. Spawn the file-analyser per cache-missed node

Invoke the file-analyser subagent via the Agent tool, one node at a time (parallel-spawn is fine for independent nodes — they don't share state). Construct the prompt as:

NODE_ID: <id>
NODE_KIND: <kind>
AXIS: <axis>
PATH: <path>
REPO: <repo>
REPO_ROOT_ABS: <absolute, e.g. /home/.../work/odd/{repo}>
SCAFFOLD_EDGES:
  imports: [...]
  imported-by: [...]
  exposes: [...]
  configures: [...]
  mounts: [...]
NODE_METADATA: <verbatim from nodes.jsonl's metadata block>
SIDECAR_TARGET: <absolute path>
WORKSPACE_ROOT_ABS: <absolute, e.g. /home/.../work/odd/odd-team>
EXISTING_SIDECAR: <if a sidecar exists, the verbatim content; else "(none)">

The subagent's tool surface is fixed by the .claude/agents/file-analyser.md frontmatter (Read, Grep, Glob, WebFetch, Write). It writes the sidecar via Write to SIDECAR_TARGET and replies with Wrote: <path> + Confidence: ....

6. Validate the resulting sidecar

For each sidecar produced:

  • Run the validator: python -m lineage_extractor.cli validate-sidecar <sidecar-path> (Bash). The validator parses YAML frontmatter + named Markdown sections and verifies required fields are present.
  • If validation fails, log the failure to lineage/{repo}/enrichment.log and surface to the maintainer. Do NOT auto-retry in slice 5 — single-shot per invocation; the maintainer iterates the prompt if quality is wrong.

7. Update the manifest

After all nodes in the worklist complete (success or failure):

  • Read lineage/{repo}/manifest.yaml.
  • Add or update the enrichment block:
    • schema_version: 0.1.0
    • subagent_versions.file-analyser: file-analyser/0.1.0
    • last_enriched_commit: <repo's HEAD commit> (only advance if every node in the worklist succeeded)
    • enriched_node_count: <count of unique sidecars under understanding/>
    • total_node_count: <count of unique node IDs in nodes.jsonl>
    • enrichment_coverage: <pct>
    • last_session_id: <Claude Code session id, if available; else timestamp>
  • Append to lineage/{repo}/enrichment.log: one line per node — <timestamp>\t<session_id>\t<node_id>\t<sidecar_path>\t<confidence>\t<doc_urls_fetched>.

8. Report

Concise output:

  • Worklist size: N
  • Successful enrichments: M
  • Failed enrichments: K (list them with the validator's reason)
  • Coverage now: X% (Y/Z nodes)
  • Suggested next: /enrich --batch <axis> for the next N unenriched nodes, or /enrich <specific-path> for ad-hoc work.

Rules

  • Live-URL-only doc rule is non-negotiable. If a sidecar has a documents.declared_docs entry without last_verified_status, validation fails. The file-analyser prompt enforces this; the validator double-checks.
  • One sidecar per node. Don't enrich neighbour nodes in the same invocation — they get their own /enrich call when the maintainer chooses.
  • Don't auto-fix the source code. The file-analyser's tool surface excludes Edit. If enrichment surfaces a bug, log it as a backlog item via playbooks/follow-up-on-disk.md; don't patch the code.
  • Preserve ## Maintainer notes. If a sidecar already exists, pass its content as EXISTING_SIDECAR so the file-analyser preserves the maintainer notes block.
  • Skip auto-advance if any node failed. last_enriched_commit only advances when every node in the worklist passed validation. Partial success leaves the mark where it was.
  • Cap at --max-nodes. Token budget per session is the constraint. Default 5; the maintainer can raise if files are small.

Failure modes to surface (not auto-fix)

  • Validator rejects sidecar (missing required field, fabricated file:line, banned phrase) → log + report; maintainer iterates the prompt.
  • WebFetch fails (404 doc URL) → the sidecar records last_verified_status: 404; the doc-gap-finder reducer (slice 7) will surface these as DOC-NNN candidates.
  • Source file hash differs from substrate's nodes.jsonl (substrate is stale relative to current HEAD) → report; recommend lineage-extractor scan {repo} --full first.

Cross-references

  • Subagent: .claude/agents/file-analyser.md
  • Validator: lineage/_extractor/src/lineage_extractor/validators.py
  • ADR: adrs/drafts/agentic-code-ontology.md revision 2
  • Substrate ADR: adrs/drafts/code-lineage-substrate.md revision 2
  • Probe set: lineage/PROBES.md (extended for semantic claims per adrs/drafts/research/agentic-code-ontology/PROBES.md)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.