@hegemonart/get-design-done 1.50.0 → 1.51.0

package/reference/instinct-format.md

@@ -0,0 +1,120 @@
+---
+name: instinct-format
+type: meta-rules
+version: 1.0.0
+phase: 51
+tags: [instinct, learning, confidence, beta-prior, promotion-gate, ttl-decay]
+last_updated: 2026-06-03
+---
+
+# Instinct Unit Format
+
+An instinct is an atomic, confidence-weighted lesson the pipeline learns across design
+cycles. Where an ADR records a deliberate, hard-to-reverse decision (see `./adr-format.md`)
+and `CONTEXT.md` records agreed vocabulary (see `./context-md-format.md`), an instinct
+records a softer signal: a recurring "when X, prefer Y" reflex that earns trust by being
+seen again and again. Each unit is one trigger sentence plus a short body, stored as a YAML
+document and validated by `./schemas/instinct.schema.json`. The store
+(`scripts/lib/instinct-store.cjs`) persists, queries, promotes, and decays them.
+
+Instincts are always advisory, never directive. A fresh instinct carries low confidence and
+is offered as a suggestion; only repeated cross-project observation raises that confidence,
+and even then it is capped well below certainty.
+
+## Unit shape
+
+A unit is a YAML frontmatter block followed by a 1 to 3 paragraph body. The body explains
+the reflex in plain language: what situation fires it, what to reach for, and why.
+
+```yaml
+---
+id: prefer-token-over-hex            # kebab-case stable identifier
+trigger: When a raw color literal appears in a component, reach for a design token first.
+confidence: 0.5                      # float in [0.3, 0.9]
+domain: build                        # intake|explore|decide|build|verify|operate|utility
+scope: project                       # project|global
+project_id: abcd1234                 # sha8 of the normalized git origin (project scope)
+source: reflection                   # reflection|extract-learnings|user
+cycles_seen: 1                       # distinct cycles that surfaced this instinct
+project_ids: [abcd1234]              # distinct origins that surfaced it (promotion gate)
+first_seen: 2026-06-01               # ISO date the unit was recorded
+last_seen: 2026-06-01                # ISO date it was last surfaced (resets decay)
+---
+Hardcoded hex values drift away from the system palette over time. Routing the value
+through a token keeps one source of truth and lets a theme change land everywhere at once.
+```
+
+### Field reference
+
+- **id** (required). Kebab-case, lowercase letters and digits with single hyphens, 3 to 80
+  characters. The id is stable: touching or promoting a unit never changes it.
+- **trigger** (required). One sentence naming the situation that fires the instinct. Keep it
+  concrete enough that a reader knows when it applies.
+- **confidence** (required). A float between 0.3 and 0.9. The floor of 0.3 says a brand-new
+  instinct is a hint, not a rule. The ceiling of 0.9 says no instinct is ever certain.
+- **domain** (required). One of `intake`, `explore`, `decide`, `build`, `verify`, `operate`,
+  `utility`. These map to the Phase 50 lifecycle stages so an instinct surfaces at the right
+  moment in a cycle.
+- **scope** (required). `project` for a lesson learned in one repository, `global` for one
+  promoted after it clears the cross-project gate below.
+- **project_id** (required for project scope). The 8-character hex sha of the normalized git
+  origin, produced by `deriveProjectId`. A global unit may omit it, since a promoted instinct
+  is no longer tied to a single origin.
+- **source** (required). Which producer minted the unit: a `reflection` pass, the
+  `extract-learnings` step, or a direct `user` assertion.
+- **cycles_seen** (optional, defaults to 1). How many distinct cycles have surfaced the unit.
+- **project_ids** (optional). The set of distinct origins that surfaced it. Its size feeds the
+  promotion gate.
+- **first_seen** / **last_seen** (optional, stamped on write). ISO dates for recording and last
+  surfacing. `last_seen` resets the decay window.
+
+## The Beta(2,8) prior
+
+When an instinct is promoted to the global store it is seeded with a Beta(2,8) posterior, the
+same conservative prior the Phase 38 `design_arms` store uses. Its posterior mean is 0.2, so a
+promoted pattern still has to earn standing from real outcomes rather than starting trusted.
+The store exposes this as `INSTINCT_PRIOR = {alpha: 2, beta: 8}`. Successful outcomes add to
+`alpha`, disappointing ones add to `beta`, and the mean moves accordingly.
+
+## Promotion gate (K=2 cycles across M=2 projects)
+
+A project instinct may move to the global store only when both halves of the gate hold:
+
+1. **K = 2 cycles.** `cycles_seen` is at least 2, so the lesson repeated rather than firing once.
+2. **M = 2 projects.** The unit appears in at least 2 distinct `project_ids`, so the lesson
+   generalized beyond the repository that first taught it.
+
+`promote(id)` throws a clear error when either half is unmet, so a one-off observation in a
+single project can never leak into global advice. On a passing gate the unit is re-scoped to
+`global`, the single-origin `project_id` is dropped, the Beta(2,8) prior is applied, and the
+unit is removed from the project store. `touch(id)` is how a unit accumulates toward the gate:
+each call bumps `last_seen` and `cycles_seen` and adds the current origin to `project_ids`.
+
+## TTL decay
+
+Instincts that stop showing up should fade rather than linger as stale advice. `decay()` walks
+a scope and, for any unit not surfaced within the decay window of 6 cycles, multiplies its
+confidence by 0.9. Once a unit's confidence falls below 0.2 it is archived: the store writes it
+to `<root>/instincts/archive/<id>.json` with an `archived_at` stamp and removes it from the live
+set. Archiving is reversible by hand, so the audit trail survives. Calling `touch(id)` resets the
+window, so an instinct that keeps proving useful never decays.
+
+## Storage and recall
+
+Project units live at `<root>/instincts/instincts.json`, resolved through the worktree-aware
+root so writes land in the main checkout rather than a throwaway worktree. Global units live at
+`~/.claude/gdd/global-instincts.json`. Both files are written atomically (a temp file plus a
+rename), and JSON is always the source of truth.
+
+`query(keyword)` ranks units by how well the keyword matches their trigger, body, and domain,
+returning the best few. When `better-sqlite3` is present with its FTS5 extension the query runs
+over a small full-text index for speed; otherwise an in-memory scan answers the same query with
+the same shape. `better-sqlite3` stays a runtime probe and is never a hard dependency, so recall
+degrades gracefully wherever the native module is absent. `backendName()` reports which path is
+active.
+
+## Cross-references
+
+- Hard-to-reverse decisions belong in an ADR, not an instinct. See `./adr-format.md`.
+- Agreed domain vocabulary belongs in `CONTEXT.md`. See `./context-md-format.md`.
+- The frontmatter schema is `./schemas/instinct.schema.json`, validated under Ajv.

package/reference/registry.json

@@ -94,7 +94,7 @@
       "name": "audit-scoring",
       "path": "reference/audit-scoring.md",
       "type": "output-contract",
-      "description": "6-pillar + 7-category audit score rubric and output schema"
+      "description": "7-pillar + 7-category audit score rubric and output schema"
     },
     {
       "name": "authority-feeds",
@@ -1149,6 +1149,13 @@
       "type": "meta-rules",
       "phase": 50,
       "description": "Phase 50 auto-generated skill composition graph (mermaid): skills grouped by lifecycle stage with composes_with and next_skills edges; regenerated by scripts/generate-skill-graph.cjs and drift-gated in CI."
+    },
+    {
+      "name": "instinct-format",
+      "path": "reference/instinct-format.md",
+      "type": "meta-rules",
+      "phase": 51,
+      "description": "Phase 51 instinct unit format: YAML frontmatter (id, trigger, confidence 0.3-0.9, domain, scope, project_id, source, cycles_seen, first/last_seen) + body; promotion gate K=2/M=2; Beta(2,8) prior; TTL decay. Stored via scripts/lib/instinct-store.cjs."
     }
   ]
 }

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed."
     },
     "timestamp": {
       "type": "string",

package/reference/schemas/instinct.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/instinct.schema.json",
+  "title": "Instinct Unit",
+  "description": "An atomic, confidence-weighted design instinct learned across cycles. Validates the YAML frontmatter object of an instinct unit (see reference/instinct-format.md). Project-scoped units live at <root>/instincts/instincts.json; promoted global units live at ~/.claude/gdd/global-instincts.json. Persisted + queried by scripts/lib/instinct-store.cjs.",
+  "type": "object",
+  "required": ["id", "trigger", "confidence", "domain", "scope", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 3,
+      "maxLength": 80,
+      "description": "Kebab-case stable identifier, e.g. \"prefer-token-over-hex\". Lowercase letters, digits, single hyphens."
+    },
+    "trigger": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 280,
+      "description": "One sentence naming the situation that fires the instinct, e.g. \"When a color literal appears in a component, reach for a design token first.\""
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.3,
+      "maximum": 0.9,
+      "description": "Posterior trust in the instinct. Floor 0.3 (a fresh instinct is advisory, never directive); ceiling 0.9 (no instinct is ever certain). TTL decay multiplies this by 0.9 when the instinct goes unsurfaced."
+    },
+    "domain": {
+      "type": "string",
+      "enum": ["intake", "explore", "decide", "build", "verify", "operate", "utility"],
+      "description": "Lifecycle stage the instinct applies to, aligned to the Phase 50 lifecycle stages."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["project", "global"],
+      "description": "project = learned from one repository; global = promoted after the K/M gate across distinct projects."
+    },
+    "project_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}$",
+      "description": "8-char hex sha of the normalized git origin the instinct was first learned from. Required for project scope; optional for global (a promoted instinct is no longer tied to one origin)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["reflection", "extract-learnings", "user"],
+      "description": "Which producer minted the instinct: a reflection pass, the extract-learnings step, or a direct user assertion."
+    },
+    "cycles_seen": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "How many distinct design cycles have surfaced this instinct. Feeds the K=2 half of the promotion gate."
+    },
+    "project_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[0-9a-f]{8}$" },
+      "uniqueItems": true,
+      "description": "Set of distinct project ids that have surfaced this instinct. Its length feeds the M=2 half of the promotion gate."
+    },
+    "first_seen": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) the instinct was first recorded."
+    },
+    "last_seen": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) the instinct was last surfaced. Resets the TTL decay window."
+    },
+    "alpha": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Beta posterior success weight. Seeded from the Beta(2,8) prior on promotion."
+    },
+    "beta": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Beta posterior failure weight. Seeded from the Beta(2,8) prior on promotion."
+    },
+    "prior_class": {
+      "type": "string",
+      "description": "Tag recording which prior class seeded the posterior, e.g. \"instinct\"."
+    }
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": { "properties": { "scope": { "const": "project" } } },
+      "then": { "required": ["project_id"] }
+    }
+  ]
+}

package/reference/skill-authoring-contract.md

@@ -161,7 +161,7 @@ lifecycle stage; CI drift-gates that file with `--check`.
 ```yaml
 ---
 name: audit
-description: "Runs a design audit and prints a 6-pillar score. Use when the user wants to score the current design. Activates for requests involving audit, score, design review."
+description: "Runs a design audit and prints a 7-pillar score. Use when the user wants to score the current design. Activates for requests involving audit, score, design review."
 tools: Read, Write, Task, Glob, Bash
 composes_with: [scan]
 next_skills: [reflect]

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 88. Composition edges: 0 composes_with, 0 next_skills.
+Skills: 89. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -80,6 +80,7 @@ flowchart TD
     n_graphify["graphify"]
     n_health["health"]
     n_help["help"]
+    n_instinct["instinct"]
     n_list_pins["list-pins"]
     n_locale["locale"]
     n_new_skill["new-skill"]
@@ -115,4 +116,11 @@ flowchart TD
     n_warm_cache["warm-cache"]
     n_zoom_out["zoom-out"]
   end
+
+  n_brief -.-> n_explore
+  n_design -.-> n_verify
+  n_explore -.-> n_plan
+  n_new_project -.-> n_brief
+  n_plan -.-> n_design
+  n_verify -.-> n_ship
 ```