diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 16062aaab..2c0f143a7 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -770,6 +770,44 @@ You are a **YC office hours partner**. Your job is to ensure the problem is unde +## Brain Context (preflight) + +Before asking any clarifying questions, load the brain's structured context +for this project. The cache layer handles staleness, refresh, and stale-but- +usable fallback automatically. Skip questions whose answers are already +present in the loaded context; ground recommendations in what the brain +already knows about the user, the product, the goals, and recent decisions. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +{ + printf '## Brain Context\n\n' + printf '\n### %s\n\n' "product" + ~/.claude/skills/gstack/bin/gstack-brain-cache get product --project "$SLUG" 2>/dev/null || printf '_(no product digest available yet)_\n' + printf '\n### %s\n\n' "goals" + ~/.claude/skills/gstack/bin/gstack-brain-cache get goals --project "$SLUG" 2>/dev/null || printf '_(no goals digest available yet)_\n' + printf '\n### %s\n\n' "user-profile" + ~/.claude/skills/gstack/bin/gstack-brain-cache get user-profile 2>/dev/null || printf '_(no user-profile digest available yet)_\n' + printf '\n### %s\n\n' "recent-decisions" + ~/.claude/skills/gstack/bin/gstack-brain-cache get recent-decisions --project "$SLUG" 2>/dev/null || printf '_(no recent-decisions digest available yet)_\n' + printf '\n### %s\n\n' "salience" + ~/.claude/skills/gstack/bin/gstack-brain-cache get salience --project "$SLUG" 2>/dev/null || printf '_(no salience digest available yet)_\n' +} > /tmp/.gstack-brain-context-$$.md 2>/dev/null +[ -s /tmp/.gstack-brain-context-$$.md ] && cat /tmp/.gstack-brain-context-$$.md +rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true +``` + +**How to use this context:** +- If `product` digest names the value prop, target user, or stage — don't re-ask. +- If `goals` digest lists active goals — frame recommendations against them. +- If `recent-decisions` digest names a prior scope/architecture choice — flag if this plan contradicts. +- If `user-profile` digest carries calibration pattern statements ("tends to over-engineer security") — surface them when relevant. +- If a digest is `(no X digest available yet)`, treat that section as cold; ask the user. + +**Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, +`gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. + + ## Phase 1: Context Gathering Understand the project and the area the user wants to change. @@ -1703,6 +1741,59 @@ Present the reviewed design doc to the user via AskUserQuestion: +## Brain Calibration Write-Back (Phase 2 / gated) + +When the skill makes a typed prediction worth tracking (scope decision, +TTHW target, architectural bet, wedge commitment), it MAY write a +`kind=bet` take to the brain so a calibration profile builds over time. + +**Gated on two things:** +1. Brain trust policy for the active endpoint is `personal` (check via + `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@`). + Shared brains skip write-back to avoid polluting team calibration. +2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips + to true when upstream gbrain v0.42+ ships `takes_add` MCP op). + +When both gates pass, the write-back path uses `mcp__gbrain__takes_add` +to record a take with weight 0.9 (per SKILL_CALIBRATION_WEIGHTS). +If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with +a gstack:takes fence block (documented but uglier path). + +Mandatory take frontmatter shape: +```yaml +kind: bet +holder: +claim: +weight: 0.9 +since_date: +expected_resolution: +source_skill: office-hours +``` + +After write, invalidate the affected digests so the next preflight reflects +the new state: + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true +``` + + +## Brain Cache Background Refresh + +After the skill's work completes (and telemetry has logged), kick a +background refresh of any cache digest that's getting close to its TTL. +This is non-blocking — the user doesn't wait. Next invocation benefits +from the warm cache. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true +``` + + --- ## Phase 6: Handoff — The Relationship Closing diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index abb337549..50cd4ea75 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -71,6 +71,8 @@ You are a **YC office hours partner**. Your job is to ensure the problem is unde {{GBRAIN_CONTEXT_LOAD}} +{{BRAIN_PREFLIGHT}} + ## Phase 1: Context Gathering Understand the project and the area the user wants to change. @@ -647,6 +649,10 @@ Present the reviewed design doc to the user via AskUserQuestion: {{GBRAIN_SAVE_RESULTS}} +{{BRAIN_WRITE_BACK}} + +{{BRAIN_CACHE_REFRESH}} + --- ## Phase 6: Handoff — The Relationship Closing diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index e0d269709..284807413 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -1033,6 +1033,42 @@ smarter on their codebase over time. +## Brain Context (preflight) + +Before asking any clarifying questions, load the brain's structured context +for this project. The cache layer handles staleness, refresh, and stale-but- +usable fallback automatically. Skip questions whose answers are already +present in the loaded context; ground recommendations in what the brain +already knows about the user, the product, the goals, and recent decisions. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +{ + printf '## Brain Context\n\n' + printf '\n### %s\n\n' "product" + ~/.claude/skills/gstack/bin/gstack-brain-cache get product --project "$SLUG" 2>/dev/null || printf '_(no product digest available yet)_\n' + printf '\n### %s\n\n' "goals" + ~/.claude/skills/gstack/bin/gstack-brain-cache get goals --project "$SLUG" 2>/dev/null || printf '_(no goals digest available yet)_\n' + printf '\n### %s\n\n' "recent-decisions" + ~/.claude/skills/gstack/bin/gstack-brain-cache get recent-decisions --project "$SLUG" 2>/dev/null || printf '_(no recent-decisions digest available yet)_\n' + printf '\n### %s\n\n' "user-profile" + ~/.claude/skills/gstack/bin/gstack-brain-cache get user-profile 2>/dev/null || printf '_(no user-profile digest available yet)_\n' +} > /tmp/.gstack-brain-context-$$.md 2>/dev/null +[ -s /tmp/.gstack-brain-context-$$.md ] && cat /tmp/.gstack-brain-context-$$.md +rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true +``` + +**How to use this context:** +- If `product` digest names the value prop, target user, or stage — don't re-ask. +- If `goals` digest lists active goals — frame recommendations against them. +- If `recent-decisions` digest names a prior scope/architecture choice — flag if this plan contradicts. +- If `user-profile` digest carries calibration pattern statements ("tends to over-engineer security") — surface them when relevant. +- If a digest is `(no X digest available yet)`, treat that section as cold; ask the user. + +**Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, +`gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. + + ## Step 0: Nuclear Scope Challenge + Mode Selection ### 0A. Premise Challenge @@ -2085,6 +2121,59 @@ already knows. A good test: would this insight save time in a future session? If +## Brain Calibration Write-Back (Phase 2 / gated) + +When the skill makes a typed prediction worth tracking (scope decision, +TTHW target, architectural bet, wedge commitment), it MAY write a +`kind=bet` take to the brain so a calibration profile builds over time. + +**Gated on two things:** +1. Brain trust policy for the active endpoint is `personal` (check via + `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@`). + Shared brains skip write-back to avoid polluting team calibration. +2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips + to true when upstream gbrain v0.42+ ships `takes_add` MCP op). + +When both gates pass, the write-back path uses `mcp__gbrain__takes_add` +to record a take with weight 0.8 (per SKILL_CALIBRATION_WEIGHTS). +If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with +a gstack:takes fence block (documented but uglier path). + +Mandatory take frontmatter shape: +```yaml +kind: bet +holder: +claim: +weight: 0.8 +since_date: +expected_resolution: +source_skill: plan-ceo-review +``` + +After write, invalidate the affected digests so the next preflight reflects +the new state: + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true +``` + + +## Brain Cache Background Refresh + +After the skill's work completes (and telemetry has logged), kick a +background refresh of any cache digest that's getting close to its TTL. +This is non-blocking — the user doesn't wait. Next invocation benefits +from the warm cache. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true +``` + + ## Mode Quick Reference ``` ┌────────────────────────────────────────────────────────────────────────────────┐ diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 4e4861d62..cd51ece29 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -222,6 +222,8 @@ Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a {{GBRAIN_CONTEXT_LOAD}} +{{BRAIN_PREFLIGHT}} + ## Step 0: Nuclear Scope Challenge + Mode Selection ### 0A. Premise Challenge @@ -854,6 +856,10 @@ If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create th {{GBRAIN_SAVE_RESULTS}} +{{BRAIN_WRITE_BACK}} + +{{BRAIN_CACHE_REFRESH}} + ## Mode Quick Reference ``` ┌────────────────────────────────────────────────────────────────────────────────┐ diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 32d3e5efc..641f8bb52 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -963,6 +963,40 @@ MUST be saved to `~/.gstack/projects/$SLUG/designs/`, NEVER to `.context/`, `docs/designs/`, `/tmp/`, or any project-local directory. Design artifacts are USER data, not project files. They persist across branches, conversations, and workspaces. +## Brain Context (preflight) + +Before asking any clarifying questions, load the brain's structured context +for this project. The cache layer handles staleness, refresh, and stale-but- +usable fallback automatically. Skip questions whose answers are already +present in the loaded context; ground recommendations in what the brain +already knows about the user, the product, the goals, and recent decisions. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +{ + printf '## Brain Context\n\n' + printf '\n### %s\n\n' "product" + ~/.claude/skills/gstack/bin/gstack-brain-cache get product --project "$SLUG" 2>/dev/null || printf '_(no product digest available yet)_\n' + printf '\n### %s\n\n' "brand" + ~/.claude/skills/gstack/bin/gstack-brain-cache get brand --project "$SLUG" 2>/dev/null || printf '_(no brand digest available yet)_\n' + printf '\n### %s\n\n' "recent-decisions" + ~/.claude/skills/gstack/bin/gstack-brain-cache get recent-decisions --project "$SLUG" 2>/dev/null || printf '_(no recent-decisions digest available yet)_\n' +} > /tmp/.gstack-brain-context-$$.md 2>/dev/null +[ -s /tmp/.gstack-brain-context-$$.md ] && cat /tmp/.gstack-brain-context-$$.md +rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true +``` + +**How to use this context:** +- If `product` digest names the value prop, target user, or stage — don't re-ask. +- If `goals` digest lists active goals — frame recommendations against them. +- If `recent-decisions` digest names a prior scope/architecture choice — flag if this plan contradicts. +- If `user-profile` digest carries calibration pattern statements ("tends to over-engineer security") — surface them when relevant. +- If a digest is `(no X digest available yet)`, treat that section as cold; ask the user. + +**Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, +`gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. + + ## Step 0: Design Scope Assessment ### 0A. Initial Design Rating @@ -1825,6 +1859,57 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Brain Calibration Write-Back (Phase 2 / gated) + +When the skill makes a typed prediction worth tracking (scope decision, +TTHW target, architectural bet, wedge commitment), it MAY write a +`kind=bet` take to the brain so a calibration profile builds over time. + +**Gated on two things:** +1. Brain trust policy for the active endpoint is `personal` (check via + `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@`). + Shared brains skip write-back to avoid polluting team calibration. +2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips + to true when upstream gbrain v0.42+ ships `takes_add` MCP op). + +When both gates pass, the write-back path uses `mcp__gbrain__takes_add` +to record a take with weight 0.5 (per SKILL_CALIBRATION_WEIGHTS). +If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with +a gstack:takes fence block (documented but uglier path). + +Mandatory take frontmatter shape: +```yaml +kind: bet +holder: +claim: +weight: 0.5 +since_date: +expected_resolution: +source_skill: plan-design-review +``` + +After write, invalidate the affected digests so the next preflight reflects +the new state: + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate brand --project "$SLUG" 2>/dev/null || true +``` + + +## Brain Cache Background Refresh + +After the skill's work completes (and telemetry has logged), kick a +background refresh of any cache digest that's getting close to its TTL. +This is non-blocking — the user doesn't wait. Next invocation benefits +from the warm cache. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true +``` + + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale. diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl index 7ff17284f..32246b1b5 100644 --- a/plan-design-review/SKILL.md.tmpl +++ b/plan-design-review/SKILL.md.tmpl @@ -138,6 +138,8 @@ Report findings before proceeding to Step 0. {{DESIGN_SETUP}} +{{BRAIN_PREFLIGHT}} + ## Step 0: Design Scope Assessment ### 0A. Initial Design Rating @@ -448,6 +450,10 @@ Substitute values from the Completion Summary: {{LEARNINGS_LOG}} +{{BRAIN_WRITE_BACK}} + +{{BRAIN_CACHE_REFRESH}} + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale. diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index cacd8f76f..74c598536 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -956,6 +956,42 @@ Note the product type; it influences which persona options are offered in Step 0 --- +## Brain Context (preflight) + +Before asking any clarifying questions, load the brain's structured context +for this project. The cache layer handles staleness, refresh, and stale-but- +usable fallback automatically. Skip questions whose answers are already +present in the loaded context; ground recommendations in what the brain +already knows about the user, the product, the goals, and recent decisions. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +{ + printf '## Brain Context\n\n' + printf '\n### %s\n\n' "product" + ~/.claude/skills/gstack/bin/gstack-brain-cache get product --project "$SLUG" 2>/dev/null || printf '_(no product digest available yet)_\n' + printf '\n### %s\n\n' "developer-persona" + ~/.claude/skills/gstack/bin/gstack-brain-cache get developer-persona --project "$SLUG" 2>/dev/null || printf '_(no developer-persona digest available yet)_\n' + printf '\n### %s\n\n' "recent-decisions" + ~/.claude/skills/gstack/bin/gstack-brain-cache get recent-decisions --project "$SLUG" 2>/dev/null || printf '_(no recent-decisions digest available yet)_\n' + printf '\n### %s\n\n' "competitive-intel" + ~/.claude/skills/gstack/bin/gstack-brain-cache get competitive-intel --project "$SLUG" 2>/dev/null || printf '_(no competitive-intel digest available yet)_\n' +} > /tmp/.gstack-brain-context-$$.md 2>/dev/null +[ -s /tmp/.gstack-brain-context-$$.md ] && cat /tmp/.gstack-brain-context-$$.md +rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true +``` + +**How to use this context:** +- If `product` digest names the value prop, target user, or stage — don't re-ask. +- If `goals` digest lists active goals — frame recommendations against them. +- If `recent-decisions` digest names a prior scope/architecture choice — flag if this plan contradicts. +- If `user-profile` digest carries calibration pattern statements ("tends to over-engineer security") — surface them when relevant. +- If a digest is `(no X digest available yet)`, treat that section as cold; ask the user. + +**Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, +`gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. + + ## Step 0: DX Investigation (before scoring) The core principle: **gather evidence and force decisions BEFORE scoring, not during @@ -2003,6 +2039,57 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Brain Calibration Write-Back (Phase 2 / gated) + +When the skill makes a typed prediction worth tracking (scope decision, +TTHW target, architectural bet, wedge commitment), it MAY write a +`kind=bet` take to the brain so a calibration profile builds over time. + +**Gated on two things:** +1. Brain trust policy for the active endpoint is `personal` (check via + `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@`). + Shared brains skip write-back to avoid polluting team calibration. +2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips + to true when upstream gbrain v0.42+ ships `takes_add` MCP op). + +When both gates pass, the write-back path uses `mcp__gbrain__takes_add` +to record a take with weight 0.6 (per SKILL_CALIBRATION_WEIGHTS). +If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with +a gstack:takes fence block (documented but uglier path). + +Mandatory take frontmatter shape: +```yaml +kind: bet +holder: +claim: +weight: 0.6 +since_date: +expected_resolution: +source_skill: plan-devex-review +``` + +After write, invalidate the affected digests so the next preflight reflects +the new state: + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true + ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate developer-persona --project "$SLUG" 2>/dev/null || true +``` + + +## Brain Cache Background Refresh + +After the skill's work completes (and telemetry has logged), kick a +background refresh of any cache digest that's getting close to its TTL. +This is non-blocking — the user doesn't wait. Next invocation benefits +from the warm cache. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true +``` + + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, recommend next reviews: diff --git a/plan-devex-review/SKILL.md.tmpl b/plan-devex-review/SKILL.md.tmpl index e40f05b52..4bda52aac 100644 --- a/plan-devex-review/SKILL.md.tmpl +++ b/plan-devex-review/SKILL.md.tmpl @@ -136,6 +136,8 @@ Note the product type; it influences which persona options are offered in Step 0 --- +{{BRAIN_PREFLIGHT}} + ## Step 0: DX Investigation (before scoring) The core principle: **gather evidence and force decisions BEFORE scoring, not during @@ -787,6 +789,10 @@ If any AskUserQuestion goes unanswered, note here. Never silently default. {{LEARNINGS_LOG}} +{{BRAIN_WRITE_BACK}} + +{{BRAIN_CACHE_REFRESH}} + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, recommend next reviews: diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 66edf982a..152a4127e 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -738,6 +738,38 @@ When evaluating architecture, think "boring by default." When reviewing tests, t * For particularly complex designs or behaviors, embed ASCII diagrams directly in code comments in the appropriate places: Models (data relationships, state transitions), Controllers (request flow), Concerns (mixin behavior), Services (processing pipelines), and Tests (what's being set up and why) when the test structure is non-obvious. * **Diagram maintenance is part of the change.** When modifying code that has ASCII diagrams in comments nearby, review whether those diagrams are still accurate. Update them as part of the same commit. Stale diagrams are worse than no diagrams — they actively mislead. Flag any stale diagrams you encounter during review even if they're outside the immediate scope of the change. +## Brain Context (preflight) + +Before asking any clarifying questions, load the brain's structured context +for this project. The cache layer handles staleness, refresh, and stale-but- +usable fallback automatically. Skip questions whose answers are already +present in the loaded context; ground recommendations in what the brain +already knows about the user, the product, the goals, and recent decisions. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +{ + printf '## Brain Context\n\n' + printf '\n### %s\n\n' "product" + ~/.claude/skills/gstack/bin/gstack-brain-cache get product --project "$SLUG" 2>/dev/null || printf '_(no product digest available yet)_\n' + printf '\n### %s\n\n' "recent-decisions" + ~/.claude/skills/gstack/bin/gstack-brain-cache get recent-decisions --project "$SLUG" 2>/dev/null || printf '_(no recent-decisions digest available yet)_\n' +} > /tmp/.gstack-brain-context-$$.md 2>/dev/null +[ -s /tmp/.gstack-brain-context-$$.md ] && cat /tmp/.gstack-brain-context-$$.md +rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true +``` + +**How to use this context:** +- If `product` digest names the value prop, target user, or stage — don't re-ask. +- If `goals` digest lists active goals — frame recommendations against them. +- If `recent-decisions` digest names a prior scope/architecture choice — flag if this plan contradicts. +- If `user-profile` digest carries calibration pattern statements ("tends to over-engineer security") — surface them when relevant. +- If a digest is `(no X digest available yet)`, treat that section as cold; ask the user. + +**Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, +`gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. + + ## BEFORE YOU START: ### Design Doc Check @@ -1669,6 +1701,57 @@ already knows. A good test: would this insight save time in a future session? If +## Brain Calibration Write-Back (Phase 2 / gated) + +When the skill makes a typed prediction worth tracking (scope decision, +TTHW target, architectural bet, wedge commitment), it MAY write a +`kind=bet` take to the brain so a calibration profile builds over time. + +**Gated on two things:** +1. Brain trust policy for the active endpoint is `personal` (check via + `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@`). + Shared brains skip write-back to avoid polluting team calibration. +2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips + to true when upstream gbrain v0.42+ ships `takes_add` MCP op). + +When both gates pass, the write-back path uses `mcp__gbrain__takes_add` +to record a take with weight 0.7 (per SKILL_CALIBRATION_WEIGHTS). +If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with +a gstack:takes fence block (documented but uglier path). + +Mandatory take frontmatter shape: +```yaml +kind: bet +holder: +claim: +weight: 0.7 +since_date: +expected_resolution: +source_skill: plan-eng-review +``` + +After write, invalidate the affected digests so the next preflight reflects +the new state: + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true + # (no per-skill invalidation targets configured) +``` + + +## Brain Cache Background Refresh + +After the skill's work completes (and telemetry has logged), kick a +background refresh of any cache digest that's getting close to its TTL. +This is non-blocking — the user doesn't wait. Next invocation benefits +from the warm cache. + +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true +``` + + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale. diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 8a167c14b..09f5b163a 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -75,6 +75,8 @@ When evaluating architecture, think "boring by default." When reviewing tests, t * For particularly complex designs or behaviors, embed ASCII diagrams directly in code comments in the appropriate places: Models (data relationships, state transitions), Controllers (request flow), Concerns (mixin behavior), Services (processing pipelines), and Tests (what's being set up and why) when the test structure is non-obvious. * **Diagram maintenance is part of the change.** When modifying code that has ASCII diagrams in comments nearby, review whether those diagrams are still accurate. Update them as part of the same commit. Stale diagrams are worse than no diagrams — they actively mislead. Flag any stale diagrams you encounter during review even if they're outside the immediate scope of the change. +{{BRAIN_PREFLIGHT}} + ## BEFORE YOU START: ### Design Doc Check @@ -321,6 +323,10 @@ Substitute values from the Completion Summary: {{GBRAIN_SAVE_RESULTS}} +{{BRAIN_WRITE_BACK}} + +{{BRAIN_CACHE_REFRESH}} + ## Next Steps — Review Chaining After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.