Keep a compact, evidence-backed checkpoint so the next session can resume without trusting a stale conversation summary.
Create a small baseline at the start; reconcile it at the beginning and end of every meaningful work session.
Bring this context first
- Current Git state and changed files.
- Observed command/test results and relevant browser or runtime evidence.
- The plan phase, blockers and exact action permissions.
Record state, not a diary
Begin with the branch or worktree, current phase and next action. Summarize completed outcomes with evidence paths or commands. Avoid pasting an entire chat transcript. A useful checkpoint lets another person understand what is safe to continue within a minute.
Separate built, tested and released
A component can be implemented but not tested. A test can pass locally while a hosted integration remains unavailable. A preview can be ready without production approval. Use explicit statuses and attach the evidence to the code revision or file hashes it actually covers. Mark it stale when relevant code changes.
Make the next action executable
“Continue backend” forces the next session to infer scope. “Verify P-01's cross-owner denial using the two synthetic users; do not deploy” identifies a bounded action and a stop point. List blockers, missing access and the decision owner. Include how to reproduce a failure without storing secrets or real customer records.
Reconcile before resuming
Read the checkpoint, then inspect the current repository and relevant runtime state. If they disagree, investigate the difference and update the document from evidence. Never revert newer work just to make the checkpoint true. Progress files reduce rediscovery; they do not prevent context loss, hallucination or concurrent edits by themselves.
One project. A concrete example.
Request Desk is a fictional app for a solo consultant. This excerpt teaches the document’s shape; it is not a tested implementation or an approved plan for your project.
# Request Desk — session checkpoint Status: EXAMPLE ONLY / not evidence from a real product Branch: feature/request-create | Revision: example-commit Current phase: P-01 (R-01) Implemented: form and server create handler. Verified: title validation fixture passed locally at example-commit. Unverified: hosted persistence and cross-owner read denial. Blocked: local database unavailable; owner to restore test access. Next action: with synthetic users A/B, verify ownership denial before starting P-02. Recheck repository state first. Permissions: local edits/tests only; no production data, push or deploy. Changed files: [actual paths go here] Evidence: [exact command/result/report, not a made-up pass] Handoff: preserve uncommitted work; do not reset the database.
Start with a useful skeleton.
Replace the bracketed fields with project facts. Keep unknowns visible. Use the established document path if your repository already has one.
# Progress
Updated: [date/time/timezone] | Maintainer: [name]
Repo/worktree: [path] | Branch/revision: [actual value]
Inputs: PRD [revision], plan [revision]
## Current state
- Active phase / requirement IDs:
- Last observed event:
- Allowed actions / closed gates:
## Completed and evidence
| Outcome | Code anchor | Check/result | Evidence location |
| --- | --- | --- | --- |
| [outcome] | [commit or hash] | [passed/failed/skipped/unverified] | [path] |
## In progress
- Changed files and unfinished behavior:
- User-owned changes to preserve:
## Blockers and decisions
- [Issue, reproducible evidence, owner, needed input]
## Next exact action
- [Small task and expected proof]
- Stop if:
## Release state
- Local / preview / production (separate):
- Remaining verification:
- Rollback/recovery reference:
## Session handoff
- Commands run and outcomes:
- Stale evidence to recheck:
- Archived history reference (only if needed):The document-writing prompt.
Supply the inputs before running it. This prompt requests a draft for review, not automatic implementation. The displayed text is exactly what the copy button uses.
Act as a careful session recorder. Reconcile .context/progress.md with the current repo and this session's actual evidence. Do not change application code, discard work, run migrations or publish anything.
Repository: [path]. Active plan phase: [ID]. Session evidence: [commands/results or paths]. Permissions: [exact allowed actions].
Read the previous checkpoint, relevant plan and current Git state. If you cannot inspect them, say so and produce a draft from the supplied evidence only. Do not invent commits, timestamps, test passes or deployment status. Preserve other people's changes.
Record the current branch/revision, active requirement/phase, completed outcomes with code anchors and evidence, unfinished changes, blockers with owners, and one exact next action. Distinguish implemented, locally verified, preview-verified and production-released. Label checks passed, failed, skipped or unverified; mark older evidence stale when relevant source changed.
Keep this a compact current-state summary, not a chat transcript. Retain unresolved risks and permissions even when shortening old history. If docs disagree with code, report the contradiction rather than rewriting the code to fit the log. Finish with a restart instruction and explicit stop conditions.
DETAILED WORKFLOW
Compare the latest checkpoint with current branch, revision, changed files and available command output. Classify outcomes as complete, in progress, blocked or unverified. For completed work record the relevant requirement or phase and evidence location. Preserve failed checks, skipped checks, unresolved risks and permission boundaries. Name one next action with prerequisites and allowed scope. Archive history by reference only when it no longer describes active work.
REQUIRED OUTPUT
Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results.
QUALITY CHECK
Do not treat an earlier assistant summary as execution evidence. Separate local, preview and production status. Mark proof stale when the files or environment it covered have changed. Check that another session can identify the correct repository and resume without guessing. Never include secrets, private records or unsupported completion claims.
ACTION BOUNDARY
Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review.A second pass for the gaps.
Run this after reviewing the first draft yourself. Supply the source documents and evidence it needs. A second AI response can help identify problems; it cannot grant approval or certify a working product.
Review .context/progress.md for [project]. This is a review task; do not edit code or publish.
INPUTS
Document/revision: [path or pasted draft]
Related requirements and current source: [paths]
Known constraints and owner decisions: [list]
Available verification evidence: [paths or none]
Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred.
DOCUMENT-SPECIFIC REVIEW
Do not treat an earlier assistant summary as execution evidence. Separate local, preview and production status. Mark proof stale when the files or environment it covered have changed. Check that another session can identify the correct repository and resume without guessing. Never include secrets, private records or unsupported completion claims.
Review these acceptance questions individually:
1. Could another person continue from the next action without guessing?
2. Does every claimed pass have real evidence tied to a code state?
3. Are local, preview and production statuses separate?
4. Are blockers, permissions and work to preserve still visible?
OUTPUT
Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works.Review before you build.
- Could another person continue from the next action without guessing?
- Does every claimed pass have real evidence tied to a code state?
- Are local, preview and production statuses separate?
- Are blockers, permissions and work to preserve still visible?
The mistake to avoid
Writing “all done” after a successful build while data access, errors or deployment remain unverified.
Keep it current
Reconcile at session start and update at a meaningful checkpoint or handoff. Archive long history only when the current record still preserves unresolved decisions and evidence links.
Tool adapters and session prompts live in the Context Engine workflow. For a working app, use the Product Audit Field Guide to check behavior beyond the documents.
Before you hand it to your AI.
When should progress.md be updated?
At meaningful checkpoints: after a verified slice, a blocking discovery, a scope change or before ending a session. Updating after every keystroke adds noise. Waiting until the conversation is exhausted risks losing the exact failure or next action. Record the evidence while it is still easy to identify.
Is a chat summary enough?
A summary is useful context, but it is not proof that code or tests match the description. Link the branch, relevant files and verification evidence. On resume, compare the checkpoint with actual state. Mark disagreements instead of confidently continuing from an old narrative.
How do I keep the file from growing forever?
Keep current phase, recent verified outcomes, unresolved risks and one next action near the top. Move older closed history to a linked archive when needed. Do not remove an unresolved failure or permission boundary simply to make the file shorter. The next session needs current truth more than a complete diary.
What should I record when tests cannot run?
Record the exact check, the reason it was skipped or blocked, and what evidence is missing. Distinguish a missing service from a failed assertion. State the next step that would make the check possible. Do not replace a runtime test with a code inspection and report the original test as passed.
How do multiple contributors use one progress file?
Agree who owns the active checkpoint and refer to separate task evidence when work runs in parallel. Include branch or worktree identity so results do not get attributed to the wrong code. Preserve newer edits and reconcile conflicting checkpoints explicitly; do not overwrite another contributor’s status from memory.
What does a useful next action look like?
Name a bounded task, its prerequisite and its verification. For example: on the listed branch, inspect the failed cross-owner request test, fix only the permission boundary and rerun that test. “Continue improving the app” provides neither a scope limit nor a way to know when to stop.