@lifeaitools/rdc-skills 0.24.41 → 0.25.0

package/guides/lessons-learned-spec.md

@@ -1,159 +1,153 @@
----
-mdk_schema_version: "1.0"
-doc_type: guide
-system: claude-workflow
-status: active
-owner: infrastructure
-created: 2026-06-08
-last_reviewed: 2026-06-08
-source_of_truth: true
-supersedes: []
-depends_on:
-  - ".claude/rules/architectural-change-approval.md"
-  - ".rdc/guides/output-contract.md"
-tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
----
-
-# Lessons-Learned Capture & Triage — Spec
-
-> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
-> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
-> something writes it down, and the weekly housekeeping pass turns those lessons into
-> actual fixes (rules, skill docs, work_items).
-
----
-
-## Why this exists
-
-Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
-gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
-makes capture a **routine exit step** of every long skill, and triage a **routine phase**
-of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
-
-Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
-propose-rule for one domain. This generalizes that pattern fleet-wide.
-
----
-
-## Storage — directory of per-lesson files
-
-Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
-
-```
-.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
-```
-
-- One file per lesson (NOT a single appended file) so parallel agents finishing at the
-  same time never collide on one file in git.
-- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
-  `preplan`, `review`, `release`, `collab`).
-- `<short-slug>` is 2–4 kebab words naming the lesson.
-
-A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
-when something was genuinely learned (see § When to capture).
-
----
-
-## Lesson file schema
-
-```markdown
----
-id: <YYYY-MM-DD>-<skill>-<short-slug>
-date: "<YYYY-MM-DD>"
-skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
-session: <session-id or short ref>
+---
+mdk_schema_version: "1.0"
+doc_type: guide
+system: claude-workflow
+status: active
+owner: infrastructure
+created: 2026-06-08
+last_reviewed: 2026-06-08
+source_of_truth: true
+supersedes: []
+depends_on:
+  - ".claude/rules/architectural-change-approval.md"
+  - ".rdc/guides/output-contract.md"
+tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
+---
+
+# Lessons-Learned Capture & Triage — Spec
+
+> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
+> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
+> something writes it down, and the weekly housekeeping pass turns those lessons into
+> actual fixes (rules, skill docs, work_items).
+
+---
+
+## Why this exists
+
+Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
+gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
+makes capture a **routine exit step** of every long skill, and triage a **routine phase**
+of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
+
+Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
+propose-rule for one domain. This generalizes that pattern fleet-wide.
+
+---
+
+## Storage — directory of per-lesson files
+
+Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
+
+```
+.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
+```
+
+- One file per lesson (NOT a single appended file) so parallel agents finishing at the
+  same time never collide on one file in git.
+- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
+  `preplan`, `review`, `release`, `collab`).
+- `<short-slug>` is 2–4 kebab words naming the lesson.
+
+A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
+when something was genuinely learned (see § When to capture).
+
+---
+
+## Lesson file schema
+
+```markdown
+---
+id: <YYYY-MM-DD>-<skill>-<short-slug>
+date: "<YYYY-MM-DD>"
+skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
+session: <session-id or short ref>
 scope: simple | architectural          # triage routing — see § Scope gate
-lesson_status: open | triaged | applied | wont-fix
-area: infra | skill | guide | rule | schema | ui | content | other
-links:
-  commits: []                          # SHAs that relate to the lesson
-  memory: []                           # memory file slugs, if a memory was also written
-  work_items: []                       # work_item UUIDs spawned during triage
----
-
-## What happened
-<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
-
-## Root cause
-<one paragraph — the evidenced cause, not a guess>
-
-## The fix / rule
+status: open | triaged | applied | wont-fix
+area: infra | skill | guide | rule | schema | ui | content | other
+links:
+  commits: []                          # SHAs that relate to the lesson
+  memory: []                           # memory file slugs, if a memory was also written
+  work_items: []                       # work_item UUIDs spawned during triage
+---
+
+## What happened
+<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
+
+## Root cause
+<one paragraph — the evidenced cause, not a guess>
+
+## The fix / rule
 <what should change so this never recurs: a rule edit, skill-doc line, code change,
-or a check. Cite a same-run related commit as context when useful, but keep
-lesson_status: open until the weekly triage audit records the final outcome.>
-```
-
+or a check. If already applied in the same run, say so and link the commit.>
+```
+
 `scope` is the single most important field — it routes triage:
-
-- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
-  skill, a missing grep guard. Housekeeping routes these through `rdc:fixit` or
-  `rdc:plan` -> `rdc:build`; it never applies them outside an RDC work item.
-- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
-  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
-  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
-  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
-
+
+- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
+  skill, a missing grep guard. Housekeeping applies these directly.
+- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
+  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
+  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
+  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
+
 When unsure, mark `architectural`.
 
-### Legacy status migration
-
-Older lesson files may use `status` instead of `lesson_status`. During weekly
-intake, before filtering or clustering, normalize every lesson that has
-`status` and no `lesson_status` by moving the unchanged value to
-`lesson_status` and removing the legacy key. Record each migration in the
-weekly report. Do not reinterpret a legacy value or create a work item merely
-because it was migrated.
-
----
-
-## When to capture (at skill exit)
-
-Write a lesson when ANY of these were true during the run:
-
-1. A root cause turned out to be different from the first theory (a wrong assumption).
-2. The standard/documented path didn't work and you had to do something non-obvious.
-3. A gate, check, or doc was missing and its absence cost a round.
-4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
-5. A hook blocked you and the block revealed a real gap (not just your mistake).
-
-Do NOT capture: routine success, your own one-off typo, anything already fully documented
-in a rule/guide. If a durable user preference or correction was involved, also write a
-`memory` (this spec and memory are complementary — link them).
-
----
-
-## Capture procedure (the exit step long skills call)
-
-At the end of a long skill run, before the final verdict line:
-
-1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
+---
+
+## When to capture (at skill exit)
+
+Write a lesson when ANY of these were true during the run:
+
+1. A root cause turned out to be different from the first theory (a wrong assumption).
+2. The standard/documented path didn't work and you had to do something non-obvious.
+3. A gate, check, or doc was missing and its absence cost a round.
+4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
+5. A hook blocked you and the block revealed a real gap (not just your mistake).
+
+Do NOT capture: routine success, your own one-off typo, anything already fully documented
+in a rule/guide. If a durable user preference or correction was involved, also write a
+`memory` (this spec and memory are complementary — link them).
+
+---
+
+## Capture procedure (the exit step long skills call)
+
+At the end of a long skill run, before the final verdict line:
+
+1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
 2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
-   Set `lesson_status: open`; a captured lesson is never self-marked as applied.
-3. Set `scope` honestly (`simple` vs `architectural`).
-4. Commit the lesson file(s) on `develop` alongside the run's other commits.
-5. Mention in the verdict/summary that N lessons were captured.
-
----
-
+   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
+   the commit linked).
+3. Set `scope` honestly (`simple` vs `architectural`).
+4. Commit the lesson file(s) on `develop` alongside the run's other commits.
+5. Mention in the verdict/summary that N lessons were captured.
+
+---
+
 ## Triage procedure (rdc:housekeeping, weekly)
 
-`rdc:housekeeping` uses this strict order. It prevents duplicate plans and fixits, gathers every architectural answer before changes, and keeps each executable change inside an RDC work item.
-
-1. Normalize legacy `status` fields as described above, then read all `.rdc/lessons/*.md` with `lesson_status: open` and cluster by `area` + root-cause similarity.
-2. **Resolution audit before routing:** for every cluster, inspect the relevant code, rules, skills, guides, tests, recent commits, linked work items, and existing mitigations. Record what was inspected, the evidence, and one result: `already-fixed`, `sufficiently-mitigated`, or `still-open`. Do not create an `rdc:fixit`, `rdc:plan`, or `rdc:build` item before this audit.
-3. Resolve no-work clusters from the audit: link the prior commit and set `lesson_status: applied` for `already-fixed`; set `lesson_status: wont-fix` for a sufficient mitigation with its remaining-risk reason. Leave partially mitigated clusters open.
-4. **Architectural report and interview:** before any file changes, report every still-open architectural decision with options, tradeoffs, recommendation, risks, and audit evidence. Create the complete interview list, ask each required question in attended mode, and record every question, answer, decision, rationale, and affected cluster. Gather all answers before the first fix. In unattended mode, create deduplicated `human_items` decision records and defer unresolved choices.
-5. **RDC routing:** route each approved still-open cluster through a complete work item and either `rdc:fixit` (only under its scope limit; it creates the sole work item) or `rdc:plan` -> `rdc:build`. Include cluster and lesson ids in the fixit description or planned task. No direct edits are allowed. Complete the required checklist, implementation report, review, validator closure, commit, and push. Deploy deployable targets to dev through RDC and record the evidence; record `not applicable` for non-deployable work.
-6. Run `rdc:review` across each completed action batch. Mark lessons `lesson_status: applied` only after review passes and the linked commit is pushed; mark deferred and declined clusters `triaged` or `wont-fix` with their linked evidence.
-7. Write the full weekly lessons report with cluster audit, architectural report, interview Q&A, RDC action register, deployment evidence, and counts for open, deduped, already fixed, mitigated, applied, triaged, wont-fix, deferred, fixits, builds, review passes, and dev deployments.
-
-Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
-
----
-
-## Skills that capture (the long-running set)
-
-`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
-
-Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
-when one of these skills ends a run with findings but no new `.rdc/lessons/` file.
+`rdc:housekeeping` adds a **Lessons triage** phase:
+
+1. Read all `.rdc/lessons/*.md` with `status: open`.
+2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
+3. For each cluster:
+   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
+     commit it, set the lesson(s) `status: applied` and link the commit.
+   - `scope: architectural` → do NOT edit. Present the issue + options via
+     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
+     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
+     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
+   - Not worth fixing → `status: wont-fix` with a one-line reason.
+4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
+
+Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
+
+---
+
+## Skills that capture (the long-running set)
+
+`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
+
+Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
+when one of these skills ends a run with findings but no new `.rdc/lessons/` file.

package/guides/output-contract.md

@@ -1,108 +1,108 @@
-# RDC Skill Output Contract
-> Every `rdc:*` skill MUST follow this contract. Non-negotiable.
-
-## Why
-
-The user has zero visibility when skills narrate tool calls and dump raw output.
-A wall of JSON, MCP responses, and "let me check X..." chatter buries the one
-thing they need: **is this working or not, and what step are we on?**
-
-## The contract
-
-1. **One checklist per invocation.** Show it upfront, update it in place as items
-   progress, print it again at the end with a 1-line verdict.
-
-2. **Checklist markers:**
-   - `[ ]` pending
-   - `[~]` in progress (currently executing)
-   - `[x]` done
-   - `[!]` failed
-   - `[-]` skipped (with one-word reason in parens)
-
-3. **NO narration of tool calls.** Forbidden phrases: "Let me...", "I'll check...",
-   "Now reading...", "Let me fetch...", "Let me verify...". Tool calls happen
-   silently. The checklist is the communication channel.
-
-4. **NO raw tool output in chat.** No MCP JSON, no log dumps, no UUIDs, no
-   SQL result tables, no curl bodies — unless a checklist item explicitly asks
-   for one (e.g., "show HTTP status"). Everything else is consumed silently and
-   folded into checklist state.
-
-5. **Failures are one sentence.** When `[!]` fires, print ONE sentence on what
-   failed and what you're doing about it. Stack traces, full error messages,
-   and debug dumps go in memory, not in chat.
-
-6. **Verdict line.** End every invocation with one line:
-   - `✅ <skill>: <outcome> in Nm Ns`
-   - `⚠️ <skill>: <N findings> — <next action>`
-   - `❌ <skill>: <one-sentence reason>`
-
-   ⛔ **The verdict emoji (✅ / ⚠️ / ❌) MUST be the FIRST character of the final
-   line — never prefix it with `**Verdict:**` or any other text.** The enforcing
-   Stop-hook checks that a line *begins* with the emoji; `**Verdict:** ✅ PASS …`
-   reads as a verdict to a human but FAILS the machine check because the line
-   starts with `**Verdict:`, not `✅` (lesson 2026-06-08-collab-verdict-line-must-start-with-emoji).
-
-   > This guide is the source under `guides/output-contract.md`; it is mirrored to
-   > `regen-root/.rdc/guides/output-contract.md` by the installer. Edit only the
-   > rdc-skills source here — never the mirror.
-
-7. **Interactive checklists only when human input is required.** If the skill
-   needs a decision (pick an epic, confirm a destructive op), ask ONE question,
-   then resume.
-
-8. **TaskCreate is internal.** If you use TaskCreate/TodoWrite for internal
-   tracking, that's fine — but the checklist shown to the user is the one
-   defined in the skill's markdown, not the raw task list.
-
-## Template
-
-Every skill invocation prints, in order:
-
-```
-<Skill Name>: <one-line subject>
-[ ] Step 1
-[ ] Step 2
-[ ] Step 3
-...
-```
-
-Then executes silently, re-rendering the checklist when state changes (tools
-like CLI agents that stream output should refresh in place). At the end:
-
-```
-<Skill Name>: <one-line subject>
-[x] Step 1
-[x] Step 2
-[x] Step 3
-✅ <verdict>
-```
-
-## What the skill may additionally emit
-
-- **One question at a time** when input is required
-- **One-sentence status updates** at major state transitions (optional)
-- **Final artifacts** if the skill's output is itself a file/report/diff — link,
-  don't inline the full content
-
-## What the skill MUST NOT emit
-
-- Tool call narration
-- Raw MCP responses
-- JSON dumps
-- Log tails
-- SQL result grids
-- UUIDs unless asked
-- "I'm going to..." preambles
-- "Let me now..." transitions
-- Summaries of what just happened (the checklist shows it)
-- Apologies for verbosity
-
-## Enforcement
-
-If a skill violates this contract, the user will say "squelch" — at which point
-any in-flight narration stops, only the checklist + verdict is shown for the
-remainder of the session.
-
-Skills SHOULD self-enforce by treating every tool call as silent and every
-user-facing emission as a deliberate checklist update.
+# RDC Skill Output Contract
+> Every `rdc:*` skill MUST follow this contract. Non-negotiable.
+
+## Why
+
+The user has zero visibility when skills narrate tool calls and dump raw output.
+A wall of JSON, MCP responses, and "let me check X..." chatter buries the one
+thing they need: **is this working or not, and what step are we on?**
+
+## The contract
+
+1. **One checklist per invocation.** Show it upfront, update it in place as items
+   progress, print it again at the end with a 1-line verdict.
+
+2. **Checklist markers:**
+   - `[ ]` pending
+   - `[~]` in progress (currently executing)
+   - `[x]` done
+   - `[!]` failed
+   - `[-]` skipped (with one-word reason in parens)
+
+3. **NO narration of tool calls.** Forbidden phrases: "Let me...", "I'll check...",
+   "Now reading...", "Let me fetch...", "Let me verify...". Tool calls happen
+   silently. The checklist is the communication channel.
+
+4. **NO raw tool output in chat.** No MCP JSON, no log dumps, no UUIDs, no
+   SQL result tables, no curl bodies — unless a checklist item explicitly asks
+   for one (e.g., "show HTTP status"). Everything else is consumed silently and
+   folded into checklist state.
+
+5. **Failures are one sentence.** When `[!]` fires, print ONE sentence on what
+   failed and what you're doing about it. Stack traces, full error messages,
+   and debug dumps go in memory, not in chat.
+
+6. **Verdict line.** End every invocation with one line:
+   - `✅ <skill>: <outcome> in Nm Ns`
+   - `⚠️ <skill>: <N findings> — <next action>`
+   - `❌ <skill>: <one-sentence reason>`
+
+   ⛔ **The verdict emoji (✅ / ⚠️ / ❌) MUST be the FIRST character of the final
+   line — never prefix it with `**Verdict:**` or any other text.** The enforcing
+   Stop-hook checks that a line *begins* with the emoji; `**Verdict:** ✅ PASS …`
+   reads as a verdict to a human but FAILS the machine check because the line
+   starts with `**Verdict:`, not `✅` (lesson 2026-06-08-collab-verdict-line-must-start-with-emoji).
+
+   > This guide is the source under `guides/output-contract.md`; it is mirrored to
+   > `regen-root/.rdc/guides/output-contract.md` by the installer. Edit only the
+   > rdc-skills source here — never the mirror.
+
+7. **Interactive checklists only when human input is required.** If the skill
+   needs a decision (pick an epic, confirm a destructive op), ask ONE question,
+   then resume.
+
+8. **TaskCreate is internal.** If you use TaskCreate/TodoWrite for internal
+   tracking, that's fine — but the checklist shown to the user is the one
+   defined in the skill's markdown, not the raw task list.
+
+## Template
+
+Every skill invocation prints, in order:
+
+```
+<Skill Name>: <one-line subject>
+[ ] Step 1
+[ ] Step 2
+[ ] Step 3
+...
+```
+
+Then executes silently, re-rendering the checklist when state changes (tools
+like CLI agents that stream output should refresh in place). At the end:
+
+```
+<Skill Name>: <one-line subject>
+[x] Step 1
+[x] Step 2
+[x] Step 3
+✅ <verdict>
+```
+
+## What the skill may additionally emit
+
+- **One question at a time** when input is required
+- **One-sentence status updates** at major state transitions (optional)
+- **Final artifacts** if the skill's output is itself a file/report/diff — link,
+  don't inline the full content
+
+## What the skill MUST NOT emit
+
+- Tool call narration
+- Raw MCP responses
+- JSON dumps
+- Log tails
+- SQL result grids
+- UUIDs unless asked
+- "I'm going to..." preambles
+- "Let me now..." transitions
+- Summaries of what just happened (the checklist shows it)
+- Apologies for verbosity
+
+## Enforcement
+
+If a skill violates this contract, the user will say "squelch" — at which point
+any in-flight narration stops, only the checklist + verdict is shown for the
+remainder of the session.
+
+Skills SHOULD self-enforce by treating every tool call as silent and every
+user-facing emission as a deliberate checklist update.