Research Log — ai-layer-kit/USAGE.md

Research Log — ai-layer-kit/USAGE.md

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

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

Score: 5/12 Status: baseline (no changes)

Criteria results

# Question (short) Result Justification
1 Audiences in 3 lines? YES Line 3 names (A)/(B) explicitly
2 Audiences kept separate? YES A=Pablo, B=client, no mixing
3 Pablo Section A self-contained? NO Step 5 forces opening SCOPING.md; step 4 references external JSON
4 Source + destination per step? NO Step 7 ambiguous on destination for mcp/codebase-search/
5 All 5 components covered? YES Steps 2-3, 4, 5, 6, 7
6 RD-0031 warning before MCP action? NO Warning at the END of step 7's sub-bullets, after Copy instruction
7 Section B jargon-free / defined? NO "subagent", "MCP", "skills paths:" leak through
8 Concrete benefit per component? YES 5/5
9 Foundry positioning explicit? YES "Vous l'exécutez chez vous…"
10 All paths consistent with arbo? NO Section C shows .claude/ai-layer/ with only README; Step 1 copies whole kit
11 QA list testable without subjectivity? NO "plain language" subjective
12 File map (C) ↔ steps (A) consistent? NO C missing files A actually copies

Observations

  • Section B is the weakest part — it leaks technical jargon ("subagent", "MCP") that defeats the client-comprehension purpose.
  • The file map in Section C reads like an aspirational layout, not a faithful representation of what Step 1 produces — major coherence gap.
  • The QA list mixes machine-testable items ("explorer cannot write") with vibe-tests ("plain language") — drag on confidence.

Iteration #1 — 2026-05-26

Score: 12/12 (was 5/12, +7) Status: Kept

Changes applied

  1. Step 4 — Inlined the hooks.Stop JSON snippet directly in the step (Pablo no longer needs to open hooks/stop-self-improve.json separately). Kept the file reference as the canonical source.
  2. Step 5 — Inlined a 4-line summary of the paths: convention (full spec still lives in SCOPING.md for depth). Pablo can execute the step without opening another file.
  3. Step 7 — (a) Moved the RD-0031 fusion warning to the first sub-bullet, before any action. (b) Clarified that only one file is added to the client repo: {repo}/.mcp.json. The reference doc stays in .claude/ai-layer/mcp/.
  4. Section B — Defined "subagent" and "MCP" inline (parenthetical lay-explanations). Replaced "skills paths:" with "Compétences ciblées par dossier". Added memory/lessons/ mention for component #2.
  5. Section C file map — Expanded to show the actual contents of .claude/ai-layer/ after Step 1's copy (8 files across 4 subdirs). Now matches reality.
  6. QA acceptance list — Replaced "User guide explains the 5 components in plain language" with "User guide contains the 5-component overview from USAGE.md Section B verbatim (or translated) — verify by diff". Removes subjectivity.

Criteria results

# Question (short) Before After Delta
1 Audiences in 3 lines? YES YES —
2 Audiences separate? YES YES —
3 Pablo self-contained? NO YES +1
4 Source + destination? NO YES +1
5 5 components covered? YES YES —
6 Warning before MCP action? NO YES +1
7 Jargon defined? NO YES +1
8 Concrete benefit? YES YES —
9 Foundry explicit? YES YES —
10 Paths consistent? NO YES +1
11 QA testable? NO YES +1
12 File map ↔ steps? NO YES +1

Observations

  • The biggest impact came from inlining: small JSON/convention snippets eliminate file-hopping for the implementer, even when the canonical source still lives elsewhere.
  • The "verify by diff" reformulation for Q11 is a reusable pattern for QA criteria — turn "plain language / good quality" into "matches X verbatim (or translated)". Captures the same intent without subjectivity.
  • Section C went from being decorative to being load-bearing — it now doubles as a verification artifact for the assembly checklist.

Next direction

Score is 12/12 against this criteria set. Stopping here. Two future-iteration candidates if the criteria evolve:

  • Add a criterion: "Does Section A explicitly identify which steps are skippable if a kit component doesn't apply?" (e.g., content-only talents skip MCP, single-domain talents skip per-domain CLAUDE.md). Currently implicit only.
  • Add a criterion: "Is the Windows/PowerShell vs Bash hook compatibility addressed in Section A?" (currently only mentioned in hooks/README.md). Both would push the criteria set to 14, not the document.