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

scan

Skill0 starsChanged 2 months agoApache-2.0View on GitHub

Run an audit scanner against ODD repositories. Reads scanner definition, picks unscanned items from coverage manifest, writes findings, updates navigation.

39 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use metrics, report and 8 more.

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.
  • GoogleSkill

    metrics

    Expertise in analyzing time-series repository health metrics, investigating root causes, and proposing proactive workflow improvements.

    Also in 3 projects that use this

  • MicrosoftSkill

    report

    Turn an exploration (threads, findings, charts) into a single Markdown report — note, blog post, executive summary, KPI dashboard, slide brief, or multi-section analytical report, with embedded charts.

    Also in 5 projects that use this

  • anombyte93Skill

    discover

    Phase 1 of the prd-taskmaster pipeline: brainstorm-driven discovery. Delegates to superpowers:brainstorming in Interactive Mode (one adaptive question at a time), or self-brainstorms in Autonomous Mode when no user is present. Intercepts before the brainstorming chain hands off to writing-plans — this skill owns the exit. Extracts constraints, calibrates scale (Solo / Team / Enterprise), and advances the pipeline to GENERATE.

    Also in 3 projects that use this

  • tuistSkill

    migrate

    Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.

    Also in 3 projects that use this

  • Google CloudSkill

    fix

    Plan a remediation strategy after a test failure.

    Also in 3 projects that use this

  • MicrosoftSkill

    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

23 rules. 0 are common, 6 are distinctive, and 17 are very specific to this project.

  • 0

    Common

    Most of the 34 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 17

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read lineage/{substrate_repo}/concepts/index.yaml + relevant detail shards (only when scanner enables concepts.yaml consultation).

    line 42
  2. Very specific:

    Read lineage/{substrate_repo}/shoebox/detail/SHB-*.md with Category: open | clustering (only when scanner enables shoebox consultation).

    line 43
  3. Very specific:

    Read lineage/{substrate_repo}/doc-gaps/index.md + per-finding details — DEDUP/PRIORITY HINT ONLY.

    line 44
  4. Very specific:

    If manifest exists: read it, pick next batch of not-scanned or changed-since-scan items

    line 47
  5. Very specific:

    If no manifest exists: run enumeration first (follow /enumerate protocol inline), then pick first batch

    line 48
  6. Distinctive:

    Follow the scanner's method systematically for EACH item in the batch

    line 58
  7. Distinctive:

    Do NOT modify any files in target repos (read-only scan)

    line 65
  8. Very specific:

    Compare description field against the live doc: If the feature's description paragraph and the live doc materially disagree → emit a …

    line 78
  9. Very specific:

    If the finding pins a per-node defect (e.g.

    line 86
  10. Very specific:

    If the same gap already exists as a DOC-GAP-NNN in doc-gaps.md: append a corroborated_by_scanner: block to its per-finding detail file — NO …

    line 87
  11. Very specific:

    If the F-NNN's description disagrees with the chain (intent-vs-implementation drift) AND the disagreement is structural → append a NEW …

    line 88
  12. Very specific:

    Coherence check: before emit: grep lineage/{substrate_repo}/{refactoring-scopes,doc-gaps,test-map,implicit-adrs}.md for any existing …

    line 94
  13. Very specific:

    Verdict tagging: every emission tagged STATIC-INFERRED or PROBE-VERIFIED (rev-13 Rule 21 D7).

    line 95
  14. Very specific:

    After writing, update the original finding file: append a - Cross-ref: enriched by F-NNN in \findings/{this-scanner-dir}/{file}.md\`` line …

    line 116
  15. Very specific:

    Every file path discovered during scanning → add to relevant navigation/domains/*.md

    line 124
  16. Very specific:

    Every repo name or integration pattern discovered (a new collector, a push-client, a platform module the scanner touched) → update …

    line 125
  17. Distinctive:

    If scanner is now 100% covered, mark as completed

    line 129
  18. Distinctive:

    Always emit (even if zero ontology clues were consumed — absence is informative).

    line 132
  19. Distinctive:

    Always check coverage manifest before scanning — never re-scan already covered items

    line 178
  20. Very specific:

    If manifest shows 100% coverage and no changed-since-scan items, report "fully scanned" and suggest re-enumeration if it's been >7 days

    line 179
  21. Very specific:

    If the scanner path doesn't exist, list available scanners from scanners/ and ask which to run

    line 180
  22. Distinctive:

    Prefer false positives over missed gaps (triager will filter later)

    line 181
  23. Very specific:

    If an item can't be scanned (file missing, access issue), mark status as error with note

    line 183

“Common” is measured: kept by at least 6 in 10 of the 34 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

Run Scanner

Execute the audit scanner at $ARGUMENTS.

Protocol

  1. Orient — Read these files (do NOT skip):
    • CLAUDE.md (system overview — nine-gate Quality Bar and Gate 9 Source-of-Truth table)
    • navigation/features.yaml (feature index)
    • navigation/architecture.md (integration-pattern + canonical-repo map; every repo name encountered during the scan is classified against this file)
    • The relevant navigation/domains/*.md for the scanner's target domain
  2. Load scanner definition at $ARGUMENTS. Extract:
    • Target repo and scope
    • Method (step-by-step)
    • Criteria (what counts as a finding)
    • Output format
    • Chunking strategy (if applicable)
    • ontology_feed: block (if present) — determines run mode (see step 2.5)

2.5. Determine run mode (rev 13):

  • If ontology_feed: is absent OR ontology_feed.enabled: false → Mode A (standalone). Continue with steps 3-10 unchanged. This is backward-compatible — every existing scanner runs as before.
  • If ontology_feed.enabled: true → Mode B (ontology-fed). Execute mode B sub-protocol below before continuing to step 3. Mode is LOCKED for the run — never switched mid-session.

Mode B sub-protocol (rev 13, per APPROACH.md §20 + scanners/README.md "Ontology-fed mode")

2.5.1. Substrate-presence check: verify lineage/{substrate_repo}/ exists with manifest.yaml, nodes.jsonl, feature-flows/index.yaml. If ANY is missing → ABORT with INSUFFICIENT-ONTOLOGY-COVERAGE: substrate not found at lineage/{substrate_repo}/. NO silent fallback to mode A — explicit mode-A re-run (with the ontology_feed: block disabled or absent) is the only path to standalone behaviour.

2.5.2. Stamp ontology commit: read lineage/{substrate_repo}/manifest.yaml:current_substrate_commit (or equivalent — last_scan_commit). Record as ontology_commit_consulted: on every emission in this run. If current_substrate_commit < HEAD - staleness_threshold_commits (default 50) OR last-modified >48h, emit WARNING: stale-ontology — trust downgraded and set ontology_corroborated: stale_warning on every emission for this run. (Per-scanner override: ontology_feed.staleness_action: abort blocks the run instead.)

2.5.3. Load coverage check: enumerate intended F-NNN entries per the scanner's ontology_feed.feature_scope_filter: (e.g. pillar_id: [P-07] or target_repo_overlap). If the filtered set is empty AND the scanner declares feature_scope_filter: → ABORT with ZERO-FEATURES-IN-SCOPE. If the filtered set covers <50% of the maintainer-expected count for this scanner's scope → emit coverage_gap_for_scan: <missing entities> to the scan-feed log and continue.

2.5.4. Load clue sources in the order declared by ontology_feed.clue_sources: (always feature-flows/detail/F-*.yaml first per Rule 21):

  • Glob lineage/{substrate_repo}/feature-flows/detail/F-*.yaml; filter by feature_scope_filter:; sort by feature_id. This is the iteration set for steps 5.B.
  • Read lineage/{substrate_repo}/concepts/index.yaml + relevant detail shards (only when scanner enables concepts.yaml consultation).
  • Read lineage/{substrate_repo}/shoebox/detail/SHB-*.md with Category: open | clustering (only when scanner enables shoebox consultation).
  • Read lineage/{substrate_repo}/doc-gaps/index.md + per-finding details — DEDUP/PRIORITY HINT ONLY. A feature absent from doc-gaps is NOT presumed documented.
  1. Check coverage manifest at state/coverage/{scanner-id-dashed}.yaml:
    • If manifest exists: read it, pick next batch of not-scanned or changed-since-scan items
    • If no manifest exists: run enumeration first (follow /enumerate protocol inline), then pick first batch
    • Batch size: 10-15 items per session (adjust based on item complexity)
  2. Load existing findings — Before scanning, read ALL existing findings files in findings/:
    • Scan every findings/*/ directory (not just the current scanner's directory — gaps cross scanner boundaries)
    • Build a mental index of: finding ID, location, short title, severity
    • During scanning, if you discover a gap that matches an existing finding (same location, same issue), do NOT create a duplicate — instead note an enrichment (see step 5)
    • Match broadly: same file + same general issue = match, even if wording differs or the scanner that found it was different
  3. Execute the scan on the selected batch:

    • Follow the scanner's method systematically for EACH item in the batch
    • Apply criteria to each item
    • Every finding must cite a Source of Truth by Gate 9 class (Repo / Integration / Config / Builder / Spec / Term / Lifecycle / Dep / Handler / Cross-repo / Backlog / Ontology (rev 13, additive)) — full table in pillars/{active}/gates.md Gate 9 + executable procedure in playbooks/claim-inventory.md. "The doc says X but the code/SoT says Y" is a finding; "the doc might be wrong" is not. If you cannot cite an SoT, the gap is speculation — either find the SoT or drop the finding.
    • For mode B (rev 13): every finding sourced from an ontology clue cites BOTH the ontology and the underlying primary-source class — e.g. Source-of-truth: Ontology[F-001:hop-1] → Repo[DataEntityDetails.tsx:56-64]. A finding citing ONLY Ontology[...] (without a primary-source class) is rejected by Gate 9 — same shape as Gate 9 already rejects "the doc might be wrong" without an SoT. The Ontology class is additive (12th class after the existing 11); it does NOT replace any existing class.
    • For SDK-backed integrations, run playbooks/unset-parameter-audit.md (Gate 5) — every unset builder parameter with an unsafe SDK default is a finding (retrospectives/LSN-002 is the canonical case).
    • For every outbound URL referenced in the doc under scan (github.com/opendatadiscovery/*, docs.opendatadiscovery.org/*, external docs), resolve the URL against navigation/architecture.md or (if missing) WebFetch / gh repo view. A broken or mis-targeted URL is a finding with SoT class Repo or Integration (retrospectives/LSN-003 is the canonical case).
    • Record findings as you go, each with its SoT citation inline
    • Do NOT modify any files in target repos (read-only scan)

    5.B. Mode B per-feature investigation (rev 13 — runs INSTEAD of step 5 when ontology_feed.enabled: true)

    The scanner's PRIMARY investigation target is lineage/{substrate_repo}/feature-flows/detail/F-*.yaml, not the scanner's traditional axes. For each in-scope F-NNN (the iteration set loaded in step 2.5.4):

    1. Read F-NNN end-to-end. Extract: feature_name, pillar_id, pillar_anchored_feature_name, description, contributing_nodes[], chain[].evidence, observed_vs_expected.facets[], status, seeded_from (if any).
    2. Derive expected doc location. From pillar_id + pillar_anchored_feature_name + system-mission.md's pillar-to-doc-path map. Check whether the page exists at documentation/docs/{expected_doc_path} and (if scanner is the canonical-accuracy variant) WebFetch the live URL.
    3. Verify against code (4-tier clue ladder):
      • file_exists (sidecar says X.java:139) → Read the cited file ±5 lines. Verified iff cited symbol present at cited line ±5.
      • assertion_about_code (sidecar says "method returns 200 OK") → Read the cited region + verify mechanically (regex / direct match). Verified iff textual claim and read evidence agree.
      • cross_layer_behaviour (chain-hop multiplicity, end-to-end DB-delta) → if probe_verifications: populated, run the cited probe; else file a probe-needed finding.
      • doc_drift (sidecar's docs_link_semantic claim) → fresh WebFetch in this session. Verified iff live status + key excerpt match sidecar within 30 days.
    4. Compare description field against the live doc. If the feature's description paragraph and the live doc materially disagree → emit a drift finding.
    5. Emit findings (per finding, cite Source-of-truth dual-class):
      • missing-page if the doc doesn't exist.
      • drift if description and live doc diverge.
      • missing-caveat per observed_vs_expected.facets[] entry not mentioned in doc.
      • ontology-drift per hop whose evidence line moved or vanished (the code shifted since the sidecar was authored).
    6. Write back (mandatory; per scanners/README.md "Ontology-fed mode" + APPROACH.md §20.5):
      • Append a scanner_reviews: entry to feature-flows/detail/F-{NNN}.yaml. APPEND-ONLY (never overwrite). Idempotency key: (scanner_id, scan_run_date).
      • If the finding pins a per-node defect (e.g. @Value consumer with unsafe default) → also annotate the relevant sidecar under lineage/{substrate_repo}/understanding/*.md (max 5 sidecars per run; above that, the cluster belongs on the F-NNN flow).
      • If the same gap already exists as a DOC-GAP-NNN in doc-gaps.md: append a corroborated_by_scanner: block to its per-finding detail file — NO new finding emitted (dedup).
      • If the F-NNN's description disagrees with the chain (intent-vs-implementation drift) AND the disagreement is structural → append a NEW shoebox thread at lineage/{substrate_repo}/shoebox/detail/SHB-NNN-{slug}.md with Category: open (the correction surface; feature-flow-builder picks it up on next pass).
    7. Per-scan-run consultation budget enforced (hard caps from ontology_feed.consultation_budget:):
      • graph-retriever ≤5: spawn for ad-hoc "does ontology cover {topic}?" queries beyond enumerated axes.
      • feature-reflector ≤3: spawn when a feature-flow's product framing disagrees with its chain AND the scanner can't independently judge.
      • odd-sme ≤2: spawn when pillar-mapping or industry-vocabulary alignment is ambiguous.
      • Above budget → backlog escalation entry (escalation: pending-sme-review), never silent drop.
    8. Coherence check before emit: grep lineage/{substrate_repo}/{refactoring-scopes,doc-gaps,test-map,implicit-adrs}.md for any existing finding matching the same (file:line) evidence. Duplicates extend via back-link, never create parallel entries.
    9. Verdict tagging: every emission tagged STATIC-INFERRED or PROBE-VERIFIED (rev-13 Rule 21 D7). A scan-run emitting only STATIC-INFERRED OK rows gets verification_class: descriptive-only and does not count toward "feature audited" status.
    10. ontology-confirmed vs ontology-extended distinction: each finding marks whether it verified what the feature-flow already named (ontology-confirmed) or surfaced new behaviour beyond it (ontology-extended).

    Mode B's findings file shape is the same as mode A; the Source-of-truth: field carries the dual-class citation.

  4. Write findings — Create the output file:
    • Path: findings/{scanner-id-dashed}/YYYY-MM-DD[-batch-N].md
    • Format: follow scanners/README.md output format exactly
    • Include summary counts at the top
    • Note which specific items were covered in this run
    • Dedup rules:
      • New gap with no prior match → new finding ID (F-NNN), written normally
      • Gap matches an existing finding from the SAME scanner → skip (already covered)
      • Gap matches an existing finding from a DIFFERENT scanner → create an enrichment entry (see format below)
    • Enrichment format (append to the findings file):
      ### F-NNN ← enriches F-XXX ({original-scanner-id})
      - **Original**: F-XXX in `findings/{original-scanner-dir}/{file}.md`
      - **New evidence**: {what this scanner found that adds to the original}
      - **Severity adjustment**: {unchanged | escalate to X | de-escalate to X} — {reason}
    • After writing, update the original finding file: append a - **Cross-ref**: enriched by F-NNN in \findings/{this-scanner-dir}/{file}.md`` line to the original finding
  5. Update coverage manifest:
    • For each item scanned: set status: scanned, record scanned_date and scanned_commit
    • Set findings_ref to the findings file path
    • Recalculate scanned_items and coverage_pct
  6. Update navigation (MANDATORY):
    • Every file path discovered during scanning → add to relevant navigation/domains/*.md
    • Every repo name or integration pattern discovered (a new collector, a push-client, a platform module the scanner touched) → update navigation/architecture.md so future Gate 9 verifications can resolve the repo in O(1) without a fresh WebFetch
    • This is a core output, not optional bookkeeping
  7. Update progress — Edit state/PROGRESS.md:
    • If scanner is now 100% covered, mark as completed

9.5. Mode B only — write scanner-feed log (rev 13):

  • Always emit (even if zero ontology clues were consumed — absence is informative).
  • Path: lineage/{substrate_repo}/scanner-feed/{YYYY-MM-DD}-{scan_run_id}.yaml.
  • Shape (per adrs/drafts/research/scanner-ontology-fusion/INTEROP.md §2.5):
    artefact: scanner-feed
    scanner_id: <scanner id from frontmatter>
    scan_run_id: SR-{ISO8601-compact}
    scan_run_date: 2026-05-27
    ontology_commit_consulted: <sha>
    mode: B                         # A | B | mixed
    clues_consumed:                 # ordered by consumption time
      - source: feature-flow
        id: F-NNN
        fields_read: [...]
        verified_against_code: true
        findings_produced: [F-NNN, F-MMM]
      - source: doc-gap
        id: DOC-GAP-NNN
        fields_read: [...]
        findings_produced: []
        dedup_action: wrote_back_corroboration
      - source: concept | shoebox | graph-search
        ...
    agent_consultations:
      feature_reflector_calls: <int>
      odd_sme_calls: <int>
      graph_retriever_calls: <int>
    write_backs:
      feature_flows: [F-NNN, ...]
      sidecars: [<slug>, ...]
      doc_gaps: [DOC-GAP-NNN, ...]
      shoebox: [SHB-NNN, ...]
    warnings:
      - "<staleness / coverage gap / budget exceeded entries>"
  • Verification-class verdict (per Rule 21 D13): if clues_consumed[] contains zero source: feature-flow entries within scope → set verification_class: corroboration-only and emit a warning. The scan-run does NOT count toward "feature audited" status until the next mode-B run completes the per-feature iteration.
  1. Report:
  • Items scanned this session: N
  • Findings this session: M
  • Coverage progress: X% (Y/Z items total)
  • Remaining items: list next batch to scan
  • Suggested: "Run /scan $ARGUMENTS again to continue (N items remaining)"

Rules

  • Always check coverage manifest before scanning — never re-scan already covered items
  • If manifest shows 100% coverage and no changed-since-scan items, report "fully scanned" and suggest re-enumeration if it's been >7 days
  • If the scanner path doesn't exist, list available scanners from scanners/ and ask which to run
  • Prefer false positives over missed gaps (triager will filter later)
  • If you find a bug in target code, note it in findings but do NOT fix it. If the defect is clearly actionable upstream (concrete file:line, operator-visible failure mode, suggested fix obvious), the triager who picks up this scan will draft it as an issues/{repo}/{PREFIX}-NNN.md upstream issue (see issues/README.md and /log-issue); record enough detail in the finding (file:line, severity, repro shape) that the triager doesn't have to re-read the code.
  • If an item can't be scanned (file missing, access issue), mark status as error with note

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.