Gdd Instinct

{{command_prefix}}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 {{command_prefix}}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:

bashCopy code
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:

bashCopy code
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

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 }):

bashCopy code
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:

Copy code
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 {{command_prefix}}reflect or {{command_prefix}}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.

bashCopy code
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 {{command_prefix}}new-skill):

bashCopy code
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:

bashCopy code
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 {{command_prefix}}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 {{command_prefix}}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