/research-lifecycle
Research corpus: stale context, R-number, research docs link (Google Docs/Deep Research report URL). NOT drive-filing.
$ golems-cli skills install research-lifecycleUpdated 1 week ago
Anti-pattern: R75 says "FTS5 is 96.9% desynced" — but it's been fixed for days. Without lifecycle management, R76 starts from wrong assumptions.
Research context files live at docs.local/claude-web/projects/<project>/. After a sprint implements research findings, these files go STALE. The local corpus is the source; Google Drive keeps the grounding provenance corpus; Deep Research receives prepared files directly by default, with Drive source off. This skill refreshes both so the next research round starts from truth, not assumptions.
HARVEST GATE — research without a harvest path is PARKED, not done
Every research dispatch — fleet-fired OR Etan-fired in his own Gemini/NotebookLM UI (standing fire=Etan rule) — MUST carry these fields at dispatch time:
| Field | Required content |
|---|---|
| harvest_owner | Named agent/LEAD who owns pulling results back into the fleet |
| harvest_trigger | What event starts harvest (report complete, Drive export lands, cron poll, Etan says "it's done", etc.) |
| export_route | Where results land for the fleet: Drive path, docs.local/research/, collab ack, brain_store digest — adapters must name this explicitly |
Research without all three = PARKED. Do not mark done, do not brain_store conclusions, do not close the collab row until harvest completes and VERIFY BEFORE STORE passes for those conclusions, or Etan explicitly parks it.
Applies to /gemini-research, /claude-desktop-research, and orc W5 research dispatches. The E07 integrity gate catches bad claims; this gate catches throughput — results sitting unharvested since morning.
INCOMING RESEARCH DOC LINK — harvest before closing
When research links arrive, the receiver's FIRST dispatch is ONE coordinator child for the whole batch, including already-filed reports. Use delegate_task with role: "research", target.providerInstanceId: "codex-worker", high effort/default tier, and label its brief codex.research.coordinator. Pass the workflow, all links and the verifier parameter. Omit isolation (shared checkout). Then end the turn. The receiver does no harvesting, splitting, verifying or filing. A non-research link does not take this route. Children briefed by a coordinator (the coordinator itself and its Drive harvest child) skip this route.
The coordinator skips intake dispatch. Per /agent-routing § Execution capability, delegate harvest/readback/filing/NotebookLM to a Drive-write-capable child; wait for its receipt while orchestrating verification. The workflow preserves R{NN}-<slug>-result, readback/export_route and PARKED-not-guessed associations.
ADMISSION BEFORE REPORT — author-held key
For project-grounded /gemini-research, the author records every admission
question's exact source answer and real first heading/line in the private
admission-key JSON under the prompt record's # Pre-fire checks. Never send the
key to the researcher. Preflight --emit refuses incomplete keys or verbatim
answer leaks. Before reading the report, extract only its admission table and run:
node skills/golem-powers/gemini-research/scripts/prompt-preflight.mjs --harvest-check admission.md R{NN}-prompt.mdEvery answer AND first-line string must match the author key. Any mismatch or
missing/extra/duplicate/non-yes row: retain the failure receipt as a fabricated
read, discard the whole result; no report reading, verification, filing or
conclusion storage. Agreement permits report verification, not acceptance of its
claims. Web-only research has no admission table/key.
Evidence: NarrationLayer R02 on 2026-11-13, six attached grounding files, six
readable: yes rows with invented answers (1.05 vs source 1.5; 0.179 vs 0.484);
the author-held key caught the fabricated reads. Earlier
Drive-grounded runs stopped with honest readable: no rows. This rule is scoped to these two
research skills.
Full SKILL.md source — includes LLM directives, anti-patterns, and technical instructions stripped from the Overview tab.
Anti-pattern: R75 says "FTS5 is 96.9% desynced" — but it's been fixed for days. Without lifecycle management, R76 starts from wrong assumptions.
Research context files live at docs.local/claude-web/projects/<project>/. After a sprint implements research findings, these files go STALE. The local corpus is the source; Google Drive keeps the grounding provenance corpus; Deep Research receives prepared files directly by default, with Drive source off. This skill refreshes both so the next research round starts from truth, not assumptions.
HARVEST GATE — research without a harvest path is PARKED, not done
Every research dispatch — fleet-fired OR Etan-fired in his own Gemini/NotebookLM UI (standing fire=Etan rule) — MUST carry these fields at dispatch time:
| Field | Required content |
|---|---|
| harvest_owner | Named agent/LEAD who owns pulling results back into the fleet |
| harvest_trigger | What event starts harvest (report complete, Drive export lands, cron poll, Etan says "it's done", etc.) |
| export_route | Where results land for the fleet: Drive path, docs.local/research/, collab ack, brain_store digest — adapters must name this explicitly |
Research without all three = PARKED. Do not mark done, do not brain_store conclusions, do not close the collab row until harvest completes and VERIFY BEFORE STORE passes for those conclusions, or Etan explicitly parks it.
Applies to /gemini-research, /claude-desktop-research, and orc W5 research dispatches. The E07 integrity gate catches bad claims; this gate catches throughput — results sitting unharvested since morning.
INCOMING RESEARCH DOC LINK — harvest before closing
When research links arrive, the receiver's FIRST dispatch is ONE coordinator child for the whole batch, including already-filed reports. Use delegate_task with role: "research", target.providerInstanceId: "codex-worker", high effort/default tier, and label its brief codex.research.coordinator. Pass the workflow, all links and the verifier parameter. Omit isolation (shared checkout). Then end the turn. The receiver does no harvesting, splitting, verifying or filing. A non-research link does not take this route. Children briefed by a coordinator (the coordinator itself and its Drive harvest child) skip this route.
The coordinator skips intake dispatch. Per /agent-routing § Execution capability, delegate harvest/readback/filing/NotebookLM to a Drive-write-capable child; wait for its receipt while orchestrating verification. The workflow preserves R{NN}-<slug>-result, readback/export_route and PARKED-not-guessed associations.
ADMISSION BEFORE REPORT — author-held key
For project-grounded /gemini-research, the author records every admission
question's exact source answer and real first heading/line in the private
admission-key JSON under the prompt record's # Pre-fire checks. Never send the
key to the researcher. Preflight --emit refuses incomplete keys or verbatim
answer leaks. Before reading the report, extract only its admission table and run:
node skills/golem-powers/gemini-research/scripts/prompt-preflight.mjs --harvest-check admission.md R{NN}-prompt.mdEvery answer AND first-line string must match the author key. Any mismatch or
missing/extra/duplicate/non-yes row: retain the failure receipt as a fabricated
read, discard the whole result; no report reading, verification, filing or
conclusion storage. Agreement permits report verification, not acceptance of its
claims. Web-only research has no admission table/key.
Evidence: NarrationLayer R02 on 2026-11-13, six attached grounding files, six
readable: yes rows with invented answers (1.05 vs source 1.5; 0.179 vs 0.484);
the author-held key caught the fabricated reads. Earlier
Drive-grounded runs stopped with honest readable: no rows. This rule is scoped to these two
research skills.
VERIFY BEFORE STORE — coordinator-owned
Verifier parameter: VERIFIER_ROLE=claude.research.verifier (API key); one override to codex.research.verifier selects subscription dispatch.
- Freeze numbered checkable claims per section (exact report quotes, locations, code/corpus revision). Fan out section verifiers using the verifier rubric. For the Claude family, use the API-key launcher, never a subscription
delegate_task. Expect ~$0.21/section or ~$0.66/100 claims for verifiers; post the batch projection before fan-out. - Send all WRONG/HALLUCINATED verdicts, a random audit of 85 VERIFIED claims (all if fewer), and a separate decision-critical UNVERIFIABLE queue to ONE adjudicator using its rubric. Default adjudicator role:
codex.research.adjudicator, effort high, service tier default. Use the other model family; Codex verifiers therefore switch it toclaude.judgment(high, never fast). Only the lead named as step owner in the brief can override the cross-family rule, in which case double the VERIFIED audit to 170 (all if fewer). - Write
VERIFY-SUMMARY.mdbeside each report, with coverage, final verdict counts, hallucination/error rates and denominators, audit seed/IDs and evidence. Store only VERIFIED facts from completed audited sections or adjudication-resolved VERIFIED claims; WRONG/HALLUCINATED only as evidenced corrections. Never store UNVERIFIABLE as fact or report-authored PROPOSAL-OK as established fact. Partial work releases only the eligible subset; pending claims remain pending.
Resolve roles from standards/model-roles.json; dispatch per /agent-routing. This gate applies to research conclusions, not ordinary non-research notes.
THE LIFECYCLE
SPRINT COMPLETES (findings implemented)
│
├─ 1. NEWEST: Add sprint results as new context file
│ (what changed, benchmark numbers, PRs merged)
│
├─ 2. CONDENSED: Compress older context files
│ (files 01-50 → one condensed file)
│
├─ 3. UPDATED: Refresh description.md with current state
│ (facts first, narrative second)
│
├─ 4. ARCHIVED: Move implemented research results
│ (R-numbers whose findings are now in code)
│
└─ 5. MIRRORED: Update Drive AND NotebookLM
(Drive required; NotebookLM only when a project notebook exists)
STEP 1: NEWEST — Add Sprint Results
After a sprint that implements research findings, create a new context file:
# File: research-context/NN-sprint-results-{date}.md
## Sprint: {description}
- Date: {date}
- PRs merged: #{N}, #{N}, #{N}
## What Changed
- {specific change 1}: {before state} → {after state}
- {specific change 2}: {before} → {after}
## Benchmark Numbers
- {metric}: {old value} → {new value}
- {metric}: {old} → {new}
## What's Still Open
- {remaining issue 1}
- {remaining issue 2}Key: Include BEFORE and AFTER states. The researcher needs to know what was the problem AND what's the current state.
Naming: Use sequential numbers (91-, 92-, 93-...) to preserve ordering. Prefix with the topic.
STEP 2: CONDENSED — Compress Stale Context
When context files accumulate (>10 files or >50KB total), condense older ones:
BEFORE:
91-swift-python-root-cause.md (from 2 weeks ago, findings implemented)
92-brainbar-ux-current-state.md (from 1 week ago, partially stale)
93-inspiration-references.md (timeless, keep as-is)
94-search-improvement-collab.md (from yesterday, still current)
AFTER:
condensed-pre-R75.md (91 + 92 merged, updated to current state)
93-inspiration-references.md (unchanged — timeless content)
94-search-improvement-collab.md (unchanged — still current)
95-R75-sprint-results.md (NEW — what the sprint changed)
Condensation rules:
- Merge files about the SAME topic into one
- Update claims to current state (remove "FTS5 is broken" if it's fixed)
- Keep timeless content as-is (references, architecture decisions with rationale)
- Remove redundant context (if 3 files say "BrainBar is Swift", keep it in one place)
STEP 3: UPDATED — Refresh description.md
The project description file tells the researcher what the project IS. It must reflect current state.
Location: docs.local/claude-web/projects/<project>/description.md
Refresh checklist:
- Architecture claims match current code (check recent PRs)
- Stats are current (chunk count, entity count, test count)
- Open issues are actually still open (not fixed in latest sprint)
- "Known limitations" haven't been resolved
- No claims about features that are stubs (check with /never-fabricate)
Format: Facts first, narrative second. Lead with numbers, follow with explanation.
## Current State (as of {date})
- Chunks: 299,972 (FTS5: 100% synced ← was 3.1% before R75 sprint)
- Entities: 166 (0.055% coverage ← needs improvement)
- Tests: 675 passing
- MCP: BrainBar (Swift daemon), 5 working tools + 3 stubs
## Architecture
{current architecture, verified against code}STEP 4: ARCHIVED — Move Implemented Research
Research results (R-number files) whose findings are fully implemented should move to archived:
# Move completed research
mv docs.local/claude-web/projects/brainlayer/R38-knowledge-graph.md \
docs.local/claude-web/projects/archived/brainlayer/Archive criteria:
- ALL findings from the research are implemented (check PRs)
- Benchmark improvements are captured in a sprint results file
- The research is >1 sprint old (keep recent research active for reference)
DON'T archive:
- Research with partially-implemented findings (keep, mark which are done)
- Timeless architectural decisions (keep in main project)
- The LATEST research result (always keep the most recent R-number)
STEP 5: MIRRORED — Drive AND NotebookLM
The local corpus is the source to push. Drive retains the provenance mirror, so the Drive refresh is blocking; NotebookLM mirroring is conditional on a project notebook existing.
-
Prove Drive auth and account identity with real calls.
"MCP connected"is NOT evidence of Drive auth. CallauthGetStatus; continue only when the real call succeeds and returns authed. Tool discovery or a connected-tool count does not pass this gate. Then verify the active account before any upload, replacement, or deletion:# Project has a NotebookLM notebook: verify both identities. bash skills/golem-powers/_shared/research/verify-account.sh # No project notebook: verify Drive without requiring NotebookLM auth state. bash skills/golem-powers/_shared/research/verify-account.sh --drive-onlyThe expected account is
RESEARCH_ACCOUNTif set, else theRESEARCH_ACCOUNT=<address>line in~/.config/research-lifecycle/research.env(outside every repo; the completion gate reads the same source). If neither is set, verification andDRIVE_ACCOUNTfail and name that file. Save the successful JSON output in the lifecycle receipt. A call failure or account mismatch is blocking; switch profiles and rerun verification instead of reconciling the wrong Drive corpus. -
Resolve the canonical destination. Use
/drive-filingfor the correct numbered folder and naming convention (its folder model and decision tree own the Drive paths; this skill does not restate them). Use/braindriveto resolve current folder IDs and the Gemini-facing corpus; do not trust stale hard-coded IDs. -
Reconcile the managed Drive corpus to local truth. Upload or replace every current local context file under the canonical project corpus, keeping local and Drive relative names identical. Upload with
mcp__google-drive__uploadFile(localPath, name, parentFolderId, mimeType)and setmimeTypefrom the extension:.md→text/markdown,.txt→text/plain,.json→application/json. Without it, a markdown file whose first bytes are<!--lands astext/html. Do not usecreateTextFileorupdateTextFilehere: they take nomimeType. Track the complete lifecycle-managed file set. Delete only previously managed Drive files that are absent locally; never delete unrelated Drive documents. Unexpected duplicate managed names fail the gate. -
Verify the refresh with a real Drive read. List/search and download/read the destination after upload. Record every local and Drive relative name,
modifiedTime, and SHA-256 content digest in a receipt. The completion command independently walks--local-root, hashes every regular file, and rejects a receipt that omits or changes any canonical local entry.DRIVE_FILESET=PASSrequires the Drive names to equal that derived inventory with no duplicates.DRIVE_FRESHNESS=PASSrequires every Drive digest to match its local source and every DrivemodifiedTimeto be at least as new. Missing or unverifiable content isFAIL. -
If the project has a NotebookLM notebook (see
/gemini-research), add updated replacement files first:source_add(notebook_id, source_type="file", file_path="updated-context.md", wait=True) -
Verify the replacements are indexed and readable, then delete the stale sources:
source_delete(source_id=stale_source, confirm=True) source_list_drive(notebook_id)Record the replacement IDs returned by
source_add, the stale source IDs, and the final indexed source IDs returned by readback.NOTEBOOKLM_FRESHNESS=PASSrequires every expected replacement ID to exist and every stale source ID to be absent; a barefresh: trueclaim does not pass. -
Update notebook instructions:
chat_configure(notebook_id, goal="custom", custom_prompt="Context files have been updated as of {date}. Previous findings about {X} are now implemented.")
Remember NP3: .py/.json/.swift/.yaml files must be renamed to .txt for NotebookLM upload.
CURATED GROUNDING FOLDER — one per research
Prepare a bounded Drive folder R{NN}-grounding/ holding only the curated documents the research needs, with a manifest (what and why, sha256, manifest_sha256); contract in /drive-filing § Research grounding folder contract. Agents prepare ONE folder holding exactly the curated grounding files with unique
names. The preparation receipt and hand-off name that folder, its manifest and
the exact files to attach; the owner attaches them when he starts the run with
Drive source off. The folder is a provenance record,
not a Deep Research access route. Its connected Drive workspace offers title SEARCH
only, with no folder listing or opening Docs by link; native Google Docs do not
fix this. If Drive is explicitly used, every title must be unique across the whole
Drive with no look-alikes or duplicates, and the prompt names each exact title.
Expect search to miss documents. Before the real run, run one cheap Deep Research
probe asking only for each named document's first line, compare all lines against
the author key, and block on any missing or mismatched line. Probe both source
routes; keep the real admission table and private key unchanged. Admission stop, plan sentence and provenance fields: /gemini-research § Curated grounding set. After harvest, archive or consolidate the folder per the contract; the harvest record carries model, settings, prompt hash and manifest hash.
GEMINI RESEARCH PROMPT PREFLIGHT — BLOCKING
Prepare the next prompt with /gemini-research's template and its structural pre-fire gate.
Before emitting any Gemini research prompt, require exactly one # Grounding block. That block must name each file supplied with the run (default: owner attaches the prepared set when starting the run, Drive source off), or each exact unique title for the optional probed Drive route, or carry the exact line None — web-only research. Agents prepare one folder with exactly the curated files and unique names; the hand-off names that folder and its files to attach; researcher text must not ask Etan to collect them.
Run the executable gate against the prompt file. It checks the block structure and invokes the legacy shared no-attach gate for file-collection instructions. It does not verify attachment delivery, title uniqueness or the probe receipt:
PROMPT=/path/to/R{NN}-prompt.md
node skills/golem-powers/research-lifecycle/scripts/lifecycle-gate.mjs \
preflight --prompt "$PROMPT"Any non-zero result means GEMINI_PREFLIGHT=FAIL: do not emit or fire the prompt. Add the missing named-document grounding or the explicit web-only line, then rerun the checks.
LIFECYCLE COMPLETION GATE — BLOCKING
Write the verification evidence to a receipt, then run the same executable gate:
{
"driveRoute": {"canonical": true, "resolvedWith": ["/drive-filing", "/braindrive"]},
"driveAuth": {"callSucceeded": true, "authed": true},
"accountVerification": {
"callSucceeded": true,
"drive_account": "<resolved research account>",
"notebooklm_account": "<resolved research account>",
"expected": "<resolved research account>",
"match": true,
"drive_only": false
},
"localFiles": [
{"name": "01-context.md", "sha256": "<64 hex chars>", "modifiedTime": "<ISO-8601>"}
],
"driveFiles": [
{"name": "01-context.md", "sha256": "<64 hex chars>", "modifiedTime": "<ISO-8601>"}
],
"notebooklm": {
"exists": true,
"expectedReplacementIds": ["source-new"],
"indexedSourceIds": ["source-new"],
"staleSourceIds": ["source-old"]
}
}LOCAL_ROOT=docs.local/claude-web/projects/PROJECT
node skills/golem-powers/research-lifecycle/scripts/lifecycle-gate.mjs \
completion --receipt /path/to/lifecycle-receipt.json --prompt "$PROMPT" \
--local-root "$LOCAL_ROOT"The lifecycle may be marked complete only when the command exits 0 and every row passes:
| Check | PASS criterion |
|---|---|
DRIVE_ROUTE | Receipt names the canonical destination resolved through /drive-filing and /braindrive |
DRIVE_AUTH | A real authGetStatus call succeeds and returns authed |
DRIVE_ACCOUNT | verify-account.sh succeeds and records the active Drive identity, equal to RESEARCH_ACCOUNT or the account in ~/.config/research-lifecycle/research.env |
LOCAL_INVENTORY | Receipt local names/digests/timestamps exactly equal the inventory derived from --local-root |
DRIVE_FILESET | Managed Drive names exactly equal the derived local inventory; no missing, extra, or duplicate managed file |
DRIVE_FRESHNESS | Every Drive SHA-256 matches local content and every Drive modifiedTime is at least as new |
NOTEBOOKLM_FRESHNESS | Explicitly not applicable, or source-ID readback proves expected replacements exist and stale sources are absent |
GEMINI_PREFLIGHT | The next Gemini prompt passes the executable grounding/no-attach preflight |
If the Drive corpus is older than the local context, the lifecycle is NOT complete. Auth failure, account mismatch, missing files, or unverifiable Drive freshness also fail the lifecycle; report the failing row instead of silently skipping it.
WHEN TO TRIGGER
| Trigger | Action |
|---|---|
| Research docs link arrives (Google Docs / Deep Research report URL) | Gatherer locates the R-number prompt; the report is filed in the sibling results/ and read back |
| Sprint merged PRs that address research findings | Run full lifecycle (Steps 1-5) |
| Before writing a new R-number research prompt | Run Steps 2-5, then the Gemini prompt preflight |
| Nightly/project maintenance runs | Check if context files are stale (Step 3 at minimum) |
| Context file count > 10 | Run Step 2 (condense) |
| Local context changed | Run Step 5 (Drive refresh is blocking) |
| NotebookLM notebook exists | Run the NotebookLM portion of Step 5 |
STALENESS DETECTION
A context file is STALE when:
- It describes a problem that's been fixed — e.g., "FTS5 is 96.9% desynced" after PR fixing it
- Its benchmark numbers are outdated — e.g., "675 tests" when there are now 720
- Its architecture claims are wrong — e.g., "Python MCP" when it's now Swift BrainBar
- It references PRs as "open" that are merged — check via
gh pr view - It's >2 sprints old and never updated — age alone signals staleness
Quick staleness check:
# Find context files older than 7 days with no updates
find docs.local/claude-web/projects/PROJECT/research-context/ -name "*.md" -mtime +7INTEGRATION
| Skill | How Research Lifecycle Uses It |
|---|---|
| Claude/Gemini research runs | Create research results → lifecycle manages them afterward |
/drive-filing | Select the canonical Drive folder and stable artifact names; archive heavy originals; docs.local lifecycle |
/braindrive | Resolve current Drive corpus locations and verify Gemini-facing files |
/gemini-research | Enforce Drive grounding preflight and NotebookLM mirroring rules |
| Nightly/project maintenance | Should check research context staleness during sweeps |
/never-fabricate | Verify claims in description.md against actual code before updating |
/orc W5 | Claude Web research prompts consume these context files |
EXAMPLE: Post-R75 Lifecycle
R75 sprint fixed FTS5 sync, implemented detect_entities_in_prompt, improved search.
- NEWEST: Create
95-R75-sprint-results.mdwith: FTS5 3.1%→100%, entity detection implemented, search hybrid mode live - CONDENSED: Merge
91-swift-python-root-cause.md+92-brainbar-ux-current-state.md→condensed-pre-R75.md(update "FTS5 broken" → "FTS5 fixed in PR #198") - UPDATED: Refresh
description.md— chunk count, entity count, test count, remove "FTS5 broken" from known issues - ARCHIVED: Move
R38-knowledge-graph.md(fully implemented) toarchived/brainlayer/ - MIRRORED: Push the current local corpus to Drive, verify Drive freshness, then replace stale NLM sources
Not yet evaluated on current models
Results will appear here once runs with a recorded model are published.
Changelog entries are derived from skill version updates. Full cascading changelog (Phase 4D) coming soon.
- +Initial release to Golems skill library
- +11 eval scenarios defined
- +Eval fixtures included