@hegemonart/get-design-done 1.50.1 → 1.51.0

package/skills/apply-reflections/SKILL.md

@@ -84,6 +84,23 @@ Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) ap
 
 KFM-catalogue proposals authored by `scripts/lib/reflector-kfm-proposer.cjs` (Phase 30.5-03 D-05) appear as a 6th proposal class. Drafts at `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md`; pre-filled 11-field schema with `TODO:` placeholders for `pattern` + `fix`. Two upstream signals share the surface (D-06): `capability_gap` clusters (≥3, no existing match) + `kfm-candidate` events (whitelist-matched articles, 1-shot). User chooses **accept** | **reject** | **defer** | **edit**. `applyAccept` appends to `reference/known-failure-modes.md` + `reference/registry.json` (`origin: incubator-kfm`); `applyReject` removes the incubator subdir; `applyDefer` stamps `deferred_until`; `applyEdit` returns the draft path for `$EDITOR`. Full procedure: `./apply-reflections-procedure.md` §[KFM-CANDIDATE].
 
+## [INSTINCT]
+
+Atomic instinct units emitted by `design-reflector` (and surfaced from `/gdd:extract-learnings`) appear as a distinct proposal class, alongside `[INCUBATOR]` and `[KFM-CANDIDATE]`. Each unit is a fenced `yaml` block under the reflector's `## Atomic instincts` section, shaped per `reference/instinct-format.md` (`id`, `trigger`, `confidence`, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). A unit is a proposal, never a stored fact - nothing lands until the user accepts it.
+
+Mirror the `[INCUBATOR]` flow:
+
+1. Discover the units: parse every `yaml` block under `## Atomic instincts` in the reflections file. Skip malformed blocks (warn on stderr, keep going).
+2. For each unit: show the parsed `trigger`, `domain`, `confidence`, and body so the user sees what would be stored.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** - call `scripts/lib/instinct-store.cjs` `add(unit, { scope, baseDir })` with the unit at its emitted `confidence`. The store owns de-duplication and `cycles_seen` bookkeeping. On success print `Stored instinct <id> (<domain>, confidence <n>).` and append `**Applied**: <date>` to the proposal block.
+2. **reject** - do not store the unit. Append `**Reviewed: rejected**` to the reflections file.
+3. **defer** - no-op; the unit re-surfaces next run. Append `**Reviewed: deferred**`.
+4. **edit** - let the user adjust `trigger`, `confidence`, or `domain`, then accept the edited unit through the same `add(...)` call. Default `scope: 'project'` (write `global` only when the unit's frontmatter says so); never edit `.design/instincts/instincts.json` directly, and promote to global via the separate gated `/gdd:instinct promote`.
+
 ## Do Not
 
 - Do not apply any proposal without the user explicitly choosing `a` or `e`.

package/skills/extract-learnings/SKILL.md

@@ -53,6 +53,22 @@ Layout of `.design/learnings/LEARNINGS.md`:
 ---
 ```
 
+### Step 3b - Dual-emit atomic instinct units (Phase 51)
+
+Alongside the prose `LEARNINGS.md`, emit atomic instinct units for every learning the extractor tags as an `instinct-candidate`. A learning is an `instinct-candidate` when it states a single trigger plus a one-line response - the same shape the reflector emits. Broader narrative learnings stay prose-only.
+
+For each `instinct-candidate`, build a unit per `reference/instinct-format.md` (frontmatter: `id`, `trigger`, `confidence` from 0.3 to 0.9, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). Set `source: extract-learnings`. Carry the learning's confidence (high / medium / low) into the numeric field (roughly 0.8 / 0.55 / 0.35), capped at 0.9.
+
+Write each unit through the store engine `scripts/lib/instinct-store.cjs` rather than by hand:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" add --scope project
+```
+
+If the engine exposes a module API only, drive `add(unit, { scope: 'project', baseDir })` from a short `node -e` script. The engine owns de-duplication and `cycles_seen` bookkeeping; do not pre-merge.
+
+The prose `LEARNINGS.md` is **retained read-only for one minor version** so existing readers keep working while tooling migrates to the units. Keep writing it; do not drop the prose path in this version.
+
 ### Step 4 - Reference file proposal (optional)
 
 After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.

package/skills/instinct/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gdd-instinct
+description: "Inspects and manages atomic instinct learning units - small, scoped, confidence-weighted patterns the pipeline accumulates across cycles. Lists the project and global instinct stores, searches them by keyword, and promotes a vetted project instinct to the global store once it has cleared the cross-project gate. Use when the user wants to see what instincts exist, find an instinct by topic, or promote one to global scope. Activates for requests involving instincts, learned patterns, instinct promotion, instinct search, or the instinct store."
+argument-hint: "[list | query <keyword> | promote <id>] [--scope project|global] [--domain <d>]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:instinct
+
+**Role:** Front end for the atomic instinct store. An instinct is a single learned pattern with a trigger, a confidence between 0.3 and 0.9, a domain, and a scope. This skill lists, searches, and promotes instincts. It never edits stored units by hand and never invents new ones - the reflector and `/gdd:extract-learnings` author them.
+
+The store engine ships at `scripts/lib/instinct-store.cjs` (authored elsewhere - this skill only calls it). Unit shape (YAML frontmatter plus a short body) is specified in `reference/instinct-format.md`. The project store lives at `.design/instincts/instincts.json`; the global store at `~/.claude/gdd/global-instincts.json`.
+
+Invoke the engine with `node`, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" <subcommand> [args]
+```
+
+If the engine exposes only a module API rather than a CLI, drive it from a short `node -e` script:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); console.log(JSON.stringify(s.list({scope:process.env.SCOPE})))"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:instinct list` | Compact table of stored instincts (default mode). |
+| `/gdd:instinct query "<keyword>"` | Search instincts by keyword; show the top matches. |
+| `/gdd:instinct promote <id>` | Promote one project instinct to the global store (gated). |
+
+Flags apply across modes:
+
+- `--scope project|global` selects which store to read. Default is `project`.
+- `--domain <d>` filters to one domain (the domain enum is defined in `reference/instinct-format.md`).
+
+## list
+
+Read the requested store and print a compact table. Call `instinct-store.list({ scope, domain, baseDir })`:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const rows=s.list({ scope: process.env.SCOPE || 'project', domain: process.env.DOMAIN || undefined }); \
+  console.log(JSON.stringify(rows));"
+```
+
+Render one row per instinct. Keep it scannable:
+
+```
+ID        DOMAIN     CONF   CYCLES  TRIGGER
+in-7f3a   tokens     0.72   3       palette has no neutral ramp
+in-91bc   layout     0.55   2       cards overflow on the 320px breakpoint
+```
+
+- `CONF` is the stored confidence (0.3 to 0.9).
+- `CYCLES` is `cycles_seen`.
+- Truncate `TRIGGER` to keep each line on one row.
+
+If the store is empty, print: `No instincts in the <scope> store yet. Run /gdd:reflect or /gdd:extract-learnings to accumulate some.`
+
+## query
+
+Search by keyword and show the closest matches. Call `instinct-store.query(keyword, { scope, baseDir, limit })`. The engine uses an FTS5 index when one is present and falls back to a plain scan otherwise; either path returns the same row shape.
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const hits=s.query(process.env.KW, { scope: process.env.SCOPE || 'project', limit: 10 }); \
+  console.log(JSON.stringify(hits));"
+```
+
+Print the top matches in the same table shape as `list`, ordered by the engine's relevance ranking. If there are no matches, say so plainly and suggest a broader keyword. Quote multi-word keywords so the shell passes one argument.
+
+## promote
+
+Promote a single project instinct into the global store so it applies across every project. Promotion is **gated**: `instinct-store.promote(id, { baseDir })` only succeeds when the instinct has been seen across at least K cycles (K=2) spanning at least M distinct project ids (M=2). The engine enforces the gate; this skill surfaces the outcome and asks the user to confirm before the write.
+
+Confirm first. Prefer `@clack/prompts`, and fall back to `AskUserQuestion` when it is absent (mirror the probe in `/gdd:new-skill`):
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.confirm({ message: 'Promote <id> to the global store?' })` from a short Node script.
+- `fallback`: ask the same yes or no question with `AskUserQuestion`.
+
+On a confirmed yes, run the promotion:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  console.log(JSON.stringify(s.promote(process.env.ID, {})));"
+```
+
+Branch on the engine result:
+
+- Promotion succeeded: print `Promoted <id> to the global store.` and show the new global row.
+- Gate not met: the engine reports how far the instinct is from the K=2 / M=2 bar. Print that plainly, for example `<id> needs 2 cycles across 2 projects; seen 1 cycle in 1 project so far. Not promoted.` Do not retry and do not force the write.
+- Unknown id: print `No instinct <id> in the project store.` and suggest `/gdd:instinct list`.
+
+If the user answers no at the confirm step, print `Promotion cancelled.` and exit without writing.
+
+## Do Not
+
+- Do not edit `.design/instincts/instincts.json` or the global store by hand. All writes go through `scripts/lib/instinct-store.cjs`.
+- Do not author new instincts here. The reflector and `/gdd:extract-learnings` emit units; this skill reads and promotes them.
+- Do not bypass the promotion gate. If the K=2 / M=2 bar is not met, report it and stop.
+- Do not modify `reference/instinct-format.md` or the store engine.
+
+## INSTINCT COMPLETE