Research Log — ai-layer-kit/skills/SCOPING.md

Research Log — ai-layer-kit/skills/SCOPING.md

Target: production-lines/digital-talent/templates/ai-layer-kit/skills/SCOPING.md Started: 2026-05-26

Iteration #0 — 2026-05-26 (baseline)

Score: 11/12

Failing criteria

  • Q9 — Doc only referenced example-scoped-skill.md. Reader landing here had no signposts back to where the convention is applied (USAGE.md step 5, assembly checklist Phase D.kit).

Iteration #1 — 2026-05-26

Score: 12/12 (was 11/12, +1) Status: Kept

Changes applied

  1. Q9 fix — Added a "## See also" section linking three artifacts: ../USAGE.md Section A step 5 (where the convention applies during assembly), ../../assembly-checklist-template.md Phase D.kit (where it's enforced at QA), and example-scoped-skill.md (concrete example).

Criteria results

# Question (short) Before After Delta
1 Rule imperative in 10 lines YES YES —
2 Exception explicit YES YES —
3 Frontmatter copy-pasteable YES YES —
4 All required fields YES YES —
5 ≥ 3 categories YES YES —
6 Anti-patterns with examples YES YES —
7 Migration checkboxes YES YES —
8 Smoke-test method YES YES —
9 Cross-references NO YES +1
10 Concrete example YES YES —
11 < 60 lines YES YES —
12 Sections earn their weight YES YES —

Observations

  • "See also" sections are 80/20: 4 lines of relative links unlocked the kit-wide navigability that was structurally missing. Worth porting to every kit doc — readers landing from a Google/grep search rarely arrive at the index page first.
  • Open flag (not a finding, parking lot for future criteria) — Q3/Q4 verified the syntax shape but not whether paths: is actually a native Claude Code skill frontmatter field (vs. a third-party convention imported from coleam00/helpline). If paths: doesn't natively scope skills in the version of Claude Code the client runs, Component #3 of the kit fails silently. A future criterion could be: "Is each frontmatter field documented in Claude Code's official skill spec, or labeled clearly as a convention requiring a hook to enforce?"

Next direction

12/12. The open-flag observation above is the most consequential follow-up — it touches the kit's foundations, not this doc.

2026-05-26 — Follow-up: bug #49835 investigation

Findings

  • paths: IS native to Claude Code (introduced v2.1.84, documented).
  • Bug #49835 (open, last activity 2026-04-17, v2.1.92, no fix, no assignee) reports that adding paths: to a .claude/skills/{name}/SKILL.md makes the skill entirely undiscoverable.
  • Related: #41721 closed as "not planned" (concerning); #45587 confirms multi-glob paths: only matches the first pattern in rules.
  • External sources (claudefa.st, Cole Medin) describe paths: as fully functional — gap between intent and current reality.

Empirical test (this repo, 2026-05-26)

  • Created C:\Projects\talent-factory\.claude\commands\paths-test.md with paths: [departments/executive/**].
  • The next session-start system-reminder listed paths-test: Test skill to verify if paths frontmatter bug in the available skills — i.e., bug #49835 does NOT block discoverability for the older .claude/commands/*.md format, only for the newer .claude/skills/{name}/SKILL.md format.
  • The kit's Component #3 currently targets .claude/commands/*.md (per SCOPING.md line 7), so this format choice incidentally avoids the bug.

Not tested yet

  • Whether /paths-test actually invokes successfully (only listed; not called).
  • Whether the paths: glob actually filters (i.e., is the skill hidden when CWD is outside departments/executive/**?). Discoverability ≠ scoping enforcement.

Decision

Composant #3 stays in v1 — no need to gel. Risk surface is narrower than initially feared.

Open follow-ups (parked, not blocking)

  • Test actual /paths-test invocation in a fresh session, both inside and outside the scoped path, to confirm filtering behavior.
  • Monitor #49835 for fix; if Anthropic deprecates paths:, ship #3 with a hook-based fallback.
  • Logged as CI-0037 for monthly re-check.