Context Refresh

PACE runs SCRIBE automatically at two points beyond the standard end-of-day cycle: during sprint planning (Day 0) and before human-gate review PRs. This page explains both triggers, their fallback behaviour, and how to run a manual refresh.

For a general introduction to SCRIBE and the context documents it maintains, see SCRIBE & Context Documents.

Why context goes stale between planning sessions

Context documents (engineering.md, security.md, devops.md, product.md) are generated by SCRIBE at the end of each sprint day from the actual files built that day. Between sprints — during the planning window when you are writing plan.yaml, reviewing estimates, and adjusting scope — the codebase is not changing, but the documents’ SHA-256 fingerprints are fixed to the end of the last sprint.

If you make changes to source files, documentation, or architecture decisions between sprints (a common pattern on active teams), those changes are invisible to PRIME and FORGE on Day 1 of the next sprint unless SCRIBE runs again before planning commits.

The two refresh triggers ensure that the context documents reviewers see in plan-approval and review PRs reflect the actual state of the codebase, not the state at the end of the previous sprint.

Planner-triggered refresh (Item 19)

When it fires

The pace-planner workflow calls _run_context_refresh() inside run_pipeline() before estimating story costs. It runs SCRIBE if either of these conditions is true:

_check_context_freshness() detects that source files listed in context.source_docs have changed (SHA-256 mismatch)
_missing_docs() finds that one or more required context documents are absent from .pace/context/

If both checks pass (context is fresh and complete), SCRIBE does not run and the planner proceeds immediately.

What happens when refresh fires

SCRIBE runs and regenerates any stale or missing documents in .pace/context/
A context_refresh_summary block is written to .pace/day-0/planner.md
The refreshed documents are committed to the pace/plan-approval branch alongside the cost estimates
The plan-approval PR body shows a summary of what was refreshed

Reviewers see a fresh engineering.md diff alongside cost estimates — so they can confirm that PRIME will have an accurate module map on Day 1.

Log output

When refresh fires, the planner logs:

[PACE][Planner] Context refresh triggered: engineering.md (stale), security.md (missing)
[PACE][Planner] Context refreshed: devops.md, engineering.md, security.md

If nothing is stale, no log line is emitted.

Non-fatal behaviour

If SCRIBE fails during the planner run (API error, timeout, or exception), the planner continues. The planner.md context_refresh_summary will contain a scribe_error field explaining what failed. The plan-approval PR is still opened with the existing (stale) context documents. A warning is printed to the CI log:

[PACE][Planner] Warning: SCRIBE failed during context refresh: <error> — continuing.

Troubleshooting a failed planner refresh

Check the CI log for the [PACE][Planner] Warning: line — it includes the exception message.
Check the API key: the most common cause is a missing or expired ANTHROPIC_API_KEY in the CI environment.
Run SCRIBE manually (see below) after fixing the root cause, then re-trigger the planner workflow.
Proceed anyway if the existing context documents are recent enough — the plan-approval PR will still contain cost estimates; only the context diff will be absent.

Human-gate-triggered refresh (Item 20)

When it fires

When a story with human_gate: true ships, the orchestrator calls _refresh_context_for_gate(day) before calling open_review_pr(). This refresh always fires on human gate stories — there is no staleness check. The intent is to give reviewers the most current picture of the codebase at the exact moment of the gate.

What happens when refresh fires

SCRIBE runs and regenerates context documents based on the current codebase state
The refreshed documents are committed to the working branch
The review PR body includes a ## Context section:

## Context

Context documents refreshed before this review:
- engineering.md (triggered by: src/auth.py, src/models/user.py)
- security.md (triggered by: src/auth.py)

Refresh cost: ~$0.03

Reviewers can inspect the refreshed engineering.md to verify that FORGE’s module map is accurate — useful for catching module drift between sprint days.

Non-fatal behaviour

If SCRIBE fails, the review PR is still opened. The ## Context section in the PR body will contain a warning:

## Context

⚠️ Context refresh failed: <error message>
Review PR opened with existing context documents.

The story is not re-run. The gate review proceeds with the existing (pre-refresh) context documents.

Manual refresh

You can trigger SCRIBE at any time outside of the daily cycle using the --refresh-context flag:

python pace/orchestrator.py --refresh-context

This runs SCRIBE unconditionally and updates all context documents in .pace/context/. Use this after:

Major refactors between sprints
Adding a new source directory
Pulling in a large external change (dependency upgrade, schema migration)

Cost of a SCRIBE refresh

A single SCRIBE run reads all source files in source.dirs (and optionally source.docs_dir) and produces four context documents. Typical cost:

Codebase size	Estimated cost
Small (<50 files)	~$0.01–0.03
Medium (50–200 files)	~$0.03–0.08
Large (200+ files)	~$0.08–0.20

Refresh runs use the analysis_model (Haiku by default). Cost is tracked in PACE_DAILY_SPEND and appears in the context_refresh_summary block in planner.md.