mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-17 15:20:11 +02:00
refactor(brain): compress GBRAIN_* resolvers, move template prose to docs/
generateGBrainContextLoad: 80 -> 115 tokens with explicit skip-header. generateGBrainSaveResults: 500-700 -> 161 tokens per skill with the skill metadata extracted into a typed skillSaveMap (slugPrefix + title + tag). Verbose prose (heredoc body, entity-stub instructions, throttle handling, backlink protocol) moved into a new doc: docs/gbrain-write-surfaces.md (Sections: §Context Load, §Save Template). The agent reads the doc on-demand only when actually saving — one Read call, cached by Claude's context. Net per-planning-skill overhead under un-suppression drops from ~1000 tokens (naive un-suppression) to ~275 tokens (compressed). Combined with the setup-time detection from prior commits, users WITHOUT gbrain pay zero overhead (block suppressed at gen-time) and users WITH gbrain pay ~275 tokens. The /investigate special-case (data-research routing in CONTEXT_LOAD) stays inline since it's skill-specific. docs/gbrain-write-surfaces.md also serves as the manual-probe reference for humans verifying live persistence + a topology summary covering trust-policy + .gbrain-source reads-only semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
+63
-40
@@ -26,72 +26,95 @@ import {
|
||||
getInvalidationTargets,
|
||||
} from '../brain-cache-spec';
|
||||
|
||||
// Per-skill slug + title + tag metadata for SAVE_RESULTS. The full save
|
||||
// template (heredoc body, entity-stub instructions, throttle handling,
|
||||
// backlinks) lives in docs/gbrain-write-surfaces.md §Save Template and is
|
||||
// read on-demand by the agent. Compressing the inline prose keeps the
|
||||
// token footprint at ~150 tokens per skill (down from ~500), so users with
|
||||
// gbrain installed pay a small overhead and users without it (whose hosts
|
||||
// have GBRAIN_SAVE_RESULTS suppressed at gen-time) pay nothing.
|
||||
interface SkillSaveMeta {
|
||||
slugPrefix: string;
|
||||
title: string;
|
||||
tag: string;
|
||||
}
|
||||
|
||||
const skillSaveMap: Record<string, SkillSaveMeta> = {
|
||||
'office-hours': { slugPrefix: 'office-hours', title: 'Office Hours', tag: 'design-doc' },
|
||||
'investigate': { slugPrefix: 'investigations', title: 'Investigation', tag: 'investigation' },
|
||||
'plan-ceo-review': { slugPrefix: 'ceo-plans', title: 'CEO Plan', tag: 'ceo-plan' },
|
||||
'plan-eng-review': { slugPrefix: 'eng-reviews', title: 'Eng Review', tag: 'eng-review' },
|
||||
'plan-design-review': { slugPrefix: 'design-reviews', title: 'Design Review', tag: 'design-review' },
|
||||
'plan-devex-review': { slugPrefix: 'devex-reviews', title: 'Devex Review', tag: 'devex-review' },
|
||||
'retro': { slugPrefix: 'retros', title: 'Retro', tag: 'retro' },
|
||||
'ship': { slugPrefix: 'releases', title: 'Release', tag: 'release' },
|
||||
'cso': { slugPrefix: 'security-audits', title: 'Security Audit', tag: 'security-audit' },
|
||||
'design-consultation': { slugPrefix: 'design-systems', title: 'Design System', tag: 'design-system' },
|
||||
};
|
||||
|
||||
export function generateGBrainContextLoad(ctx: TemplateContext): string {
|
||||
let base = `## Brain Context Load
|
||||
|
||||
Before starting this skill, search your brain for relevant context:
|
||||
**Skip this entire section if \`gbrain\` is not on PATH.**
|
||||
|
||||
1. Extract 2-4 keywords from the user's request (nouns, error names, file paths, technical terms).
|
||||
Search GBrain: \`gbrain search "keyword1 keyword2"\`
|
||||
Example: for "the login page is broken after deploy", search \`gbrain search "login broken deploy"\`
|
||||
Search returns lines like: \`[slug] Title (score: 0.85) - first line of content...\`
|
||||
2. If few results, broaden to the single most specific keyword and search again.
|
||||
3. For each result page, read it: \`gbrain get_page "<page_slug>"\`
|
||||
Read the top 3 pages for context.
|
||||
4. Use this brain context to inform your analysis.
|
||||
Extract 2-4 keywords from the user's request. Search the brain:
|
||||
\`gbrain search "<keywords>"\`. Read the top 3 results with
|
||||
\`gbrain get_page "<slug>"\`. Use that context to inform your analysis.
|
||||
|
||||
If GBrain is not available or returns no results, proceed without brain context.
|
||||
Any non-zero exit code from gbrain commands should be treated as a transient failure.`;
|
||||
If \`gbrain search\` returns no results or any non-zero exit, proceed
|
||||
without brain context. Full search/read protocol + examples:
|
||||
see \`docs/gbrain-write-surfaces.md\` §Context Load.`;
|
||||
|
||||
if (ctx.skillName === 'investigate') {
|
||||
base += `\n\nIf the user's request is about tracking, extracting, or researching structured data (e.g., "track this data", "extract from emails", "build a tracker"), route to GBrain's data-research skill instead: \`gbrain call data-research\`. This skill has a 7-phase pipeline optimized for structured data extraction.`;
|
||||
base += `\n\nFor structured-data extraction requests ("track this", "extract from emails", "build a tracker"), route to GBrain's data-research skill instead: \`gbrain call data-research\`.`;
|
||||
}
|
||||
|
||||
return base;
|
||||
}
|
||||
|
||||
export function generateGBrainSaveResults(ctx: TemplateContext): string {
|
||||
// gbrain v0.18+ renamed `put_page` → `put <slug>` and moved --title/--tags
|
||||
// into YAML frontmatter inside --content. These templates render into
|
||||
// SKILL.md files as user-facing instructions; using the old subcommand
|
||||
// ships broken copy-paste to every gstack user.
|
||||
const skillSaveMap: Record<string, string> = {
|
||||
'office-hours': 'Save the design document as a brain page:\n```bash\ngbrain put "office-hours/<project-slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "Office Hours: <project name>"\ntags: [design-doc, <project-slug>]\n---\n<design doc content in markdown>\nEOF\n)"\n```',
|
||||
'investigate': 'Save the root cause analysis as a brain page:\n```bash\ngbrain put "investigations/<issue-slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "Investigation: <issue summary>"\ntags: [investigation, <affected-files>]\n---\n<investigation findings in markdown>\nEOF\n)"\n```',
|
||||
'plan-ceo-review': 'Save the CEO plan as a brain page:\n```bash\ngbrain put "ceo-plans/<feature-slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "CEO Plan: <feature name>"\ntags: [ceo-plan, <feature-slug>]\n---\n<scope decisions and vision in markdown>\nEOF\n)"\n```',
|
||||
'retro': 'Save the retrospective as a brain page:\n```bash\ngbrain put "retros/<date>" --content "$(cat <<\'EOF\'\n---\ntitle: "Retro: <date range>"\ntags: [retro, <date>]\n---\n<retro output in markdown>\nEOF\n)"\n```',
|
||||
'plan-eng-review': 'Save the architecture decisions as a brain page:\n```bash\ngbrain put "eng-reviews/<feature-slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "Eng Review: <feature name>"\ntags: [eng-review, <feature-slug>]\n---\n<review findings and decisions in markdown>\nEOF\n)"\n```',
|
||||
'ship': 'Save the release notes as a brain page:\n```bash\ngbrain put "releases/<version>" --content "$(cat <<\'EOF\'\n---\ntitle: "Release: <version>"\ntags: [release, <version>]\n---\n<changelog entry and deploy details in markdown>\nEOF\n)"\n```',
|
||||
'cso': 'Save the security audit as a brain page:\n```bash\ngbrain put "security-audits/<date>" --content "$(cat <<\'EOF\'\n---\ntitle: "Security Audit: <date>"\ntags: [security-audit, <date>]\n---\n<findings and remediation status in markdown>\nEOF\n)"\n```',
|
||||
'design-consultation': 'Save the design system as a brain page:\n```bash\ngbrain put "design-systems/<project-slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "Design System: <project name>"\ntags: [design-system, <project-slug>]\n---\n<design decisions in markdown>\nEOF\n)"\n```',
|
||||
};
|
||||
// gbrain v0.18+ uses `gbrain put <slug>` (NOT the deprecated `put_page`
|
||||
// MCP op). Compressed in v1.50.0.0: the inline heredoc + entity-stub +
|
||||
// throttle + backlink prose moved to docs/gbrain-write-surfaces.md
|
||||
// §Save Template, which the agent reads on demand when it actually
|
||||
// saves. The compact pointer keeps non-gbrain users' token overhead
|
||||
// near zero when their host's static suppression is overridden by
|
||||
// detection.
|
||||
const meta = skillSaveMap[ctx.skillName];
|
||||
|
||||
const saveInstruction = skillSaveMap[ctx.skillName] || 'Save the skill output as a brain page if the results are worth preserving:\n```bash\ngbrain put "<slug>" --content "$(cat <<\'EOF\'\n---\ntitle: "<descriptive title>"\ntags: [<relevant>, <tags>]\n---\n<content in markdown>\nEOF\n)"\n```';
|
||||
if (!meta) {
|
||||
return `## Save Results to Brain
|
||||
|
||||
**Skip this entire section if \`gbrain\` is not on PATH.**
|
||||
|
||||
If the skill output is worth preserving, save it via
|
||||
\`gbrain put "<slug>" --content "<frontmatter + markdown>"\`. Full template
|
||||
(heredoc body, frontmatter shape, entity-stub instructions, throttle
|
||||
handling): see \`docs/gbrain-write-surfaces.md\` §Save Template.`;
|
||||
}
|
||||
|
||||
return `## Save Results to Brain
|
||||
|
||||
After completing this skill, persist the results to your brain for future reference:
|
||||
**Skip this entire section if \`gbrain\` is not on PATH.**
|
||||
|
||||
${saveInstruction}
|
||||
After completing this skill, save the output:
|
||||
|
||||
After saving the page, extract and enrich mentioned entities: for each actual person name or company/organization name found in the output, \`gbrain search "<entity name>"\` to check if a page exists. If not, create a stub page:
|
||||
\`\`\`bash
|
||||
gbrain put "entities/<entity-slug>" --content "$(cat <<'EOF'
|
||||
gbrain put "${meta.slugPrefix}/<feature-slug>" --content "$(cat <<'EOF'
|
||||
---
|
||||
title: "<Person or Company Name>"
|
||||
tags: [entity, person]
|
||||
title: "${meta.title}: <feature name>"
|
||||
tags: [${meta.tag}, <feature-slug>]
|
||||
---
|
||||
Stub page. Mentioned in <skill name> output.
|
||||
<skill output in markdown>
|
||||
EOF
|
||||
)"
|
||||
\`\`\`
|
||||
Only extract actual person names and company/organization names. Skip product names, section headings, technical terms, and file paths.
|
||||
|
||||
Throttle errors appear as: exit code 1 with stderr containing "throttle", "rate limit", "capacity", or "busy". If GBrain returns a throttle or rate-limit error on any save operation, defer the save and move on. The brain is busy — the content is not lost, just not persisted this run. Any other non-zero exit code should also be treated as a transient failure.
|
||||
|
||||
Add backlinks to related brain pages if they exist. If GBrain is not available, skip this step.
|
||||
|
||||
After brain operations complete, note in your completion output: how many pages were found in the initial search, how many entities were enriched, and whether any operations were throttled. This helps the user see brain utilization over time.`;
|
||||
Then extract person/org entities and create stub pages for each one.
|
||||
Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any
|
||||
other non-zero exit are transient — don't retry inline. Full entity-stub
|
||||
template, throttle handling, and backlink protocol:
|
||||
see \`docs/gbrain-write-surfaces.md\` §Save Template.`;
|
||||
}
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────
|
||||
|
||||
Reference in New Issue
Block a user