refresh-context

name	refresh-context
description	Keep the brand brain from going stale. Reads running-notes/refresh-schedule.md and each standing doc's refresh_by frontmatter, surfaces what is overdue or due soon, walks the Phase 1→2→3 dependency spine to catch docs made stale by upstream changes even when their own date is fine, and re-runs the generating prompt for each — carrying the prior version forward and re-stamping the dates. Use weekly as a scheduled routine, or whenever asked to refresh, re-run, or check the freshness of the brand brain or any context doc.
argument-hint	[optional: a doc name or cadence tier to refresh; default = everything overdue]

Refresh context — keep the brain from going stale

A context doc is a photograph of a moving thing. The ad account moves weekly, reviews pile up, a competitor enters, the brand relaunches. Every standing doc carries a refresh_by date; this routine watches those dates so a stale doc gets re-run instead of quietly being trusted past its shelf life. It does not silently re-run without surfacing the recommendation first.

When it runs

Weekly as a scheduled check. The check is cheap — it only re-runs docs that are actually due. Most weeks it surfaces a short list; some weeks nothing is due.

The freshness mechanism

Every context doc stamps two frontmatter fields: generated_on (the day it was produced, from get_current_time) and refresh_by (generated_on + the doc type's cadence). One aggregated view lives at running-notes/refresh-schedule.md — the file to watch. It is a view over the per-doc stamps, not a second source of truth; when the two disagree, the doc's own frontmatter wins and the schedule line is corrected.

The cadence by doc type (the dials)

• ~90 days (quarterly) — the account moves under these: ad-account-evaluation, performance-targets-and-metrics, organic-channels-inventory, visual-vocabulary, marketing-calendar-and-campaigns, the four Phase-2 strategy inputs (persona / product-priority / messaging / creator-talent) and the strategic-roadmap they synthesize.
• ~180 days (semi-annual) — these accumulate, they don't lurch: reputation-analysis, customer-journey-and-persona-discovery, category-and-market-research, community-and-forums, website-and-product-audit, personas (profile + sources + voice library + lifecycle + bias notes), voice-of-customer, the constant competitor profiles.
• ~365 days (annual) — identity rarely shifts: brand-identity-analysis, operations-and-team.
• Event-driven, not calendar — brand-profile-narrative is due when ≥2 of its sub-context docs have been re-run (90-day floor as backstop); competitor rotation refreshes constants semi-annually and rotates affinity/inspiration each cycle.
• Exempt — the audits-* family (cadence is in the name), the idea bank and briefs, and idea-evaluation (event-driven; see the evaluate-ideas skill).

Triggers that override the calendar (refresh early)

A rebrand or repositioning, a new SKU/line/launch, a pricing move (the brand's or a key competitor's), a meaningful jump in the review corpus or a new review surface, a new competitor entering or one exiting, an attribution/account-structure change that breaks comparability, or a validated finding that changes the read the doc rests on.

Dependency staleness — the phase spine

A doc can be stale while its own date is fine, because what it was built from moved. The three phases are a dependency chain and freshness flows down it: Phase 1 (audits, foundation sub-context docs, personas, voice-of-customer, competitors) → Phase 2 (the four strategy inputs → the strategic roadmap) → Phase 3 (idea evaluation, briefs). When an upstream doc's read materially changes on a re-run, every downstream doc synthesized from it is stale-by-dependency regardless of its calendar date. The edges: a Phase-1 change hits the Phase-2 strategy input(s) that rest on it; any Phase-2 strategy input change hits the strategic-roadmap; a roadmap change makes idea-evaluation due. The two event-driven rules above (brand-profile-narrative, idea-evaluation) are the same principle. See parker-system/system/refresh-cadence.md for the doctrine.

Process

1. Read the schedule. Open running-notes/refresh-schedule.md. If it is missing (a fresh brain may not have one yet), build it: walk every standing doc, read its generated_on / refresh_by frontmatter, and write one line per doc grouped by cadence tier. This becomes the file watched from here on.
2. Compare to today. Read today from get_current_time. Mark each doc overdue, due soon (within ~2 weeks), or fresh. Then scan for fired override triggers — if one has fired, the doc is due regardless of its date.
3. Walk the phase spine for dependency staleness. After the date pass, check the Phase 1→2→3 chain: for each downstream doc (the four Phase-2 strategy inputs, the strategic-roadmap, idea-evaluation), read the generated_on of the upstream docs it was built from. If any upstream is newer than the downstream and that upstream's last re-run materially changed the read — not a carry-forward-unchanged refresh — the downstream is stale by dependency, regardless of its own date. Judge materiality by reading the two versions, not by the file's timestamp alone; a touched-but-unchanged upstream does not cascade. This is what catches a roadmap built on a performance read that has since moved.
4. Surface before acting. List what is overdue / due-soon / stale-by-dependency with one line each — "your performance read is from March and it's now June; want me to refresh it?" or "the messaging strategy input predates the customer-review audit that just changed the read it rests on." Name the reason (date vs dependency) so the recommendation is legible. In an interactive run, wait for the go-ahead. In a scheduled run, refresh the overdue-and-material set automatically and report what was done and why.
5. Re-run each due doc, and note whether the read changed. A refresh is a re-run of the generating prompt, not a patch. The prompt lives in this brain at parker-system/prompts/<path>.md (or in the brain's own root prompts/ folder, for generators the brain authored itself per growing-the-brain) — it travels with the brain for exactly this, so re-run the doc's own generating prompt rather than improvising a regeneration. Take the prior version as context, carry forward what is still true, re-read the live sources the doc rests on (Parker MCP reads, the brand's own surfaces, web), and re-stamp generated_on and refresh_by. Honor the brand hard rules and load the parker-system/creative-strategy-context/ docs the doc type requires per the routing table in CLAUDE.md, including the brand lens overlay.
   • Preserve what the brand put there. A re-run regenerates from sources, so it can quietly erase tribal knowledge the brand or the team hand-added to a doc — a corrected fact, a note in their own words, a constraint they typed in, an insight they appended. That is the brand teaching Parker, and it outranks a fresh generic pass. Before overwriting, diff the new version against the prior one: anything brand-authored or hand-corrected carries forward, reconciled into the new doc, not dropped. If the live data now genuinely contradicts a brand-stated line, do not silently overwrite it — surface the conflict and offer the update, the same way a tool-sourced contradiction is handled. And when a refresh turns up a durable brand preference or correction worth keeping beyond this one doc, add it to brand-lens.md so it shapes every future output, not just this re-run.
6. Update the schedule line for every doc re-run, so refresh-schedule.md stays a true aggregate. When a re-run materially changed the read, note that on the line — it is the signal the phase-spine walk reads next cycle to decide whether downstream docs cascade.
7. Refresh the folder indexes. If a refresh added, removed, or materially changed a competitor profile or an audit, regenerate that folder's INDEX.md (competitors/INDEX.md, audits/INDEX.md) — one line per doc, filename plus what it is, newest audit noted as the present tense. These are the generated maps the always-loaded brand-profile.md points to so the planner can see everything in the growing folders without the one-pager enumerating it. Keep them in sync with the folder; they are pointers, never restated findings.
8. Close the loop. If a refresh surfaced something new — a shift the old read missed — capture it as an open loop in open-loops/ for the next roll-up, and note any idea worth keeping for harvest-ideas.
9. Log the run. Prepend one entry to running-notes/routine-log.md (create it from parker-system/templates/routine-log-template.md if it does not exist yet): the date and time, refresh-context, whether the run was scheduled or manual, what was checked (docs against refresh_by plus the phase spine), what was re-run and re-stamped, what was left fresh, and anything surfaced. This is the append-only history — never overwrite it, and never overwrite the due-date view in refresh-schedule.md with it; they are two different files. It is what proves the weekly routine actually fired and what it did each week.

Hard rules

• Never silently keep using a doc past its refresh_by, and never re-run without first surfacing the recommendation in an interactive session.
• A refresh re-runs the prompt with the prior version as context — it does not hand-edit a stale doc in place.
• The doc's own frontmatter is the source of truth; the schedule is a view. Correct the schedule to the doc, never the reverse.
• Honor the brand hard rules (see CLAUDE.md and running-notes/brand-notes-from-org.md) on every regenerated doc.
• Never let a re-run erase brand-authored content. Tribal knowledge, hand-corrections, and notes the brand or team added carry forward into the new version; a genuine data contradiction is surfaced and offered, never silently overwritten.
• Re-run the doc's own generating prompt from its home: parker-system/prompts/ for the factory generators (they travel in the mount for exactly this), or the brain's own root prompts/ for generators the brain authored itself per growing-the-brain. Those two are the whole contract — no third location. Self-contained otherwise: read only in-repo surfaces and live data sources. Do not depend on factory (parker-brain) paths — they do not exist in a cloned instance.
• Dependency staleness cascades only on a material change, and only downstream along the phase spine. A carry-forward-unchanged refresh does not force the chain to re-run; surface stale-by-dependency docs as recommendations, never auto-cascade the whole spine on a touch.

Deliverable

The due docs re-run and re-stamped, running-notes/refresh-schedule.md updated, one entry appended to running-notes/routine-log.md, and a short report of what was refreshed, what was left (and why) — separating date-overdue from stale-by-dependency — and any open loops or ideas the refresh surfaced.