condensed-context

---
name: condensed-context
description: Maintain a compact CondensedContext markdown file for durable, token-efficient project memory across long-running Codex work. Use when Codex is making repository changes, continuing work across context compaction, preserving decisions and agent changes over time, building a repo-local memory index, checking whether a CondensedContext file exists, creating one if missing, updating it after meaningful changes, compacting stale history, or tying committed and pushed changes to git commit hashes.
---

# Condensed Context

Use this skill to keep durable, low-token project memory in a repository-local markdown file.

## File

- Prefer `CondensedContext.md` at the repository root.
- If a similar file already exists, such as `CONDENSED_CONTEXT.md`, `docs/CondensedContext.md`, or a user-named context file, use the existing file and preserve its naming.
- If no CondensedContext file exists, create `CondensedContext.md` before making substantive changes.
- For larger repositories, optionally split durable memory into `docs/context/Architecture.md`, `docs/context/Decisions.md`, `docs/context/FileMap.md`, `docs/context/Validation.md`, and `docs/context/ActiveWork.md`; keep the root `CondensedContext.md` as the high-level index.
- When context files keep growing, prefer compressed `CCF/1` records over more prose. Use `CondensedContext.md` as a tiny navigation and freshness index, and store larger durable layers as compressed files such as `docs/context/Architecture.cc.md`, `docs/context/Decisions.cc.md`, `docs/context/FileMap.cc.md`, `docs/context/Validation.cc.md`, and `docs/context/ActiveWork.cc.md`.
- Prefer a sidecar full-memory file named `CondensedContext.CCF1` when the root context needs to stay human-readable. Keep `CondensedContext.md` to freshness, handoff, pointers, and the last 5-7 meaningful changes; keep the complete semantic memory graph in `CondensedContext.CCF1`.
- For repository-scale use, treat context files as a semantic memory hierarchy: root index, semantic graph, compressed subsystem summaries, detailed context, then source code.

## Start Of Work

1. Locate the repository root with git when available.
2. Check for an existing CondensedContext file.
3. If both `CondensedContext.md` and `CondensedContext.CCF1` exist, read the root file first, then read the sidecar records needed for the task.
4. Detect whether each context file is readable Markdown or compressed `CCF/1`.
5. For readable Markdown, read `Context Freshness`, `Current Focus`, `Handoff`, `Semantic Memory`, `Recent Changes`, `Validation`, and `Open Threads` before planning or editing.
6. For `CCF/1`, read `@fresh`, `@focus`, `@handoff`, `@fact`, `@constraint`, `@node`, `@rel`, `@page`, `@file`, `@validation`, `@coverage`, and `@open` records before planning or editing.
7. Compare `Last Verified Commit` or `lv` with current `HEAD` when git is available.
8. If commits differ, use `git diff --name-only <Last Verified Commit>..HEAD` or the nearest available comparison to identify changed files, then mark only affected sections stale.
9. Search `Recent Changes` or `@chg` and `@arch` records by relevant tags, filenames, IDs, or feature names instead of reading all history by default.
10. If the file is missing, create it with the readable sections below for small repositories, or create the root-plus-sidecar pair when the repository is large or the user wants maximum token savings:

```markdown
# CondensedContext

## Context Freshness
Context ID: FRESH-001
Last Verified Commit: Unknown
Current HEAD: Unknown
Generated: Unknown
Status:
- Stale until initialized against the repository.
Files requiring verification:
- None recorded yet.

## Purpose
Durable, compact memory for agent work in this repository. Keep this file short, current, and useful for future agents.

## Current Focus
Context ID: ACTIVE-001
Confidence: Low; newly initialized.
- Created by Codex; replace with the active goal or most recent project focus.

## Handoff
Context ID: HANDOFF-001
Confidence: Low; newly initialized.
- Last known state: Created by Codex.
- Next useful step: Replace this with the next concrete action.
- Validation: Not run.

## Stable Facts
Context ID: FACTS-001
Confidence: Low; newly initialized.
- None recorded yet.

## Decisions
Context ID: DECISIONS-001
Confidence: Low; newly initialized.
- None recorded yet.

## Known Constraints
Context ID: CONSTRAINTS-001
Confidence: Low; newly initialized.
- None recorded yet.

## File Map
Context ID: FILEMAP-001
Confidence: Low; newly initialized.
- None recorded yet.

## Validation Memory
Context ID: VALIDATION-001
Confidence: Low; newly initialized.
- None recorded yet.

## Coverage
Context ID: COVERAGE-001
Confidence: Low; newly initialized.
- Files indexed: Unknown
- Coverage notes: None recorded yet.

## Changes
| Date | Tags | Change | Files | Commit | Remote |
| --- | --- | --- | --- | --- | --- |

## Archived History
- None yet.

## Open Threads
Context ID: OPEN-001
Confidence: Low; newly initialized.
- None recorded yet.
```

Readable root plus sidecar pattern:

```markdown
# CondensedContext

## Context Freshness
- Last Verified Commit: Unknown
- Current HEAD: Unknown
- Status: Stale until initialized.
- Full Semantic Memory: `CondensedContext.CCF1`

## Current Focus
- Created by Codex; replace with active goal.

## Handoff
- Last known state: Created by Codex.
- Next useful step: Replace with next action.
- Validation: Not run.

## Recent Changes
| Date | Tags | Change | Files | Commit | Remote |
| --- | --- | --- | --- | --- | --- |

## Open Threads
- None recorded yet.
```

Minimal compressed equivalent:

```text
# CondensedContext
<!-- CCF/1 -->
@legend key=value; ids stable; c=H|M|L; tags comma-separated; files use aliases from @path.
@fresh id=FRESH-001 lv=Unknown head=Unknown gen=Unknown st=stale verify=none
@focus id=ACTIVE-001 c=L :: Created by Codex; replace with active goal.
@handoff id=HANDOFF-001 c=L :: state=Created by Codex; next=Replace with next action; val=not-run
@fact id=FACTS-001 c=L :: none
@dec id=DECISIONS-001 c=L :: none
@constraint id=CONSTRAINTS-001 c=L :: none
@node id=MEM-001 c=L lvl=L2 fid=lossy imp=? vol=? cost=? files=? deps=? :: none
@rel from=MEM-001 to=? kind=depends
@page id=PAGE-001 load=? skip=? trigger=?
@file id=FILEMAP-001 c=L path=? role=none
@validation id=VALIDATION-001 c=L :: none
@coverage id=COVERAGE-001 c=L files=? notes=none
@open id=OPEN-001 c=L :: none
```

## Freshness And Incremental Updates

- Keep `Context Freshness` machine-readable and near the top of the file.
- Record `Last Verified Commit`, `Current HEAD`, generation time when useful, freshness status, and files or sections requiring verification.
- Use exactly these freshness states:
  - `fresh`: context verified against current `HEAD` and no relevant uncommitted changes are present.
  - `partial`: context verified against current `HEAD`, but relevant uncommitted changes are present.
  - `stale`: current `HEAD` differs from the stored verified commit, required verification failed, or referenced files moved or disappeared.
  - `unknown`: git or source state cannot be checked.
- Keep root and sidecar freshness synchronized. If `CondensedContext.md` says `partial`, `stale`, or `unknown`, the matching `@fresh st=` value in `CondensedContext.CCF1` should say the same unless a concise note explains why they differ.
- When `Current HEAD` differs from `Last Verified Commit`, preserve the document and mark it `stale` instead of rebuilding everything.
- Use changed files to decide which sections need updates:
  - Dependency, lockfile, manifest, build config, or folder-structure changes should refresh architecture, file map, validation, and metrics sections.
  - Source-file changes should refresh only the relevant subsystem, file map entries, active work, and recent changes.
  - Documentation-only changes usually refresh decisions, README references, or context notes only when they affect durable knowledge.
- After refreshing affected sections, update `Last Verified Commit` to the verified commit when the context matches that commit.
- If the working tree has relevant uncommitted changes, keep `Last Verified Commit` at the last verified commit, set status to `partial`, and list uncommitted aliases, files, node IDs, or record IDs under `Files requiring verification` or `verify=`.
- In `CCF/1`, use `verify=<aliases-or-record-ids>` to name exactly what needs review; prefer aliases from `@path` and stable IDs from `@node`, `@file`, or `@validation`.
- Do not use freshness records to preserve sensitive details. They may name paths, aliases, technical areas, or record IDs only.

## Freshness-Aware Targeting

Use direct file-to-record targeting before broader graph invalidation:

1. Map each changed file to its `@path` alias.
2. Find `@file path=<alias>` records.
3. Find `@node files=<alias-list>` records.
4. Mark only those records stale or lower confidence unless the change affects shared config, dependencies, build behavior, or documented architecture.
5. Update `@fresh verify=<...>` with the affected aliases or record IDs.
6. Update root `Context Freshness` with the same verification target in readable form.
7. Re-read source only for targeted records unless the targeting reveals unknown or broad impact.

Freshness-aware `@node` records should include file aliases:

```text
@path S=src/session.ts
@node id=AUTH-001 c=H lvl=L2 fid=lossless imp=H vol=M cost=M files=S deps=DB-001 :: session auth issues and verifies tokens.
```

When `S` changes but the source has not been re-read yet:

```text
@fresh id=FRESH-001 lv=<old-head> head=<current-head> gen=<date> st=stale verify=S,AUTH-001
@node id=AUTH-001 c=L stale=source-changed lvl=L2 fid=lossless imp=H vol=M cost=M files=S deps=DB-001 :: session auth issues and verifies tokens; re-read S before relying on details.
```

When uncommitted work touches `S` after the context was updated against `HEAD`:

```text
@fresh id=FRESH-001 lv=<head> head=<head> gen=<date> st=partial verify=S,AUTH-001
@chg date=<date> tags=auth files=S commit=Uncommitted remote=Not-confirmed :: session auth work in progress; not verified against commit.
```

Use broader stale targeting only when a changed file has broad effects:

- dependency or lock files
- build configuration
- generated schema or migration files
- public API contracts
- files referenced by many high-importance nodes

## Compressed Context Format

Use `CCF/1` when human readability is less important than reducing tokens.
It is intentionally line-oriented, terse, and expandable by Codex:

- Start compressed files with `<!-- CCF/1 -->`.
- Keep one durable fact per record line.
- Use `@legend` to define abbreviations once per file.
- Use `@path` aliases for frequently referenced files or directories, such as `@path S=condensed-context/SKILL.md`.
- Use stable record IDs where targeted updates matter: `id=ARCH-API-001`, `id=DEC-DB-001`, `id=VAL-TEST-001`.
- Use confidence as `c=H`, `c=M`, or `c=L`; add a short stale reason with `stale=<reason>` when needed.
- Use `::` before free text; keep free text sentence-fragment sized.
- Prefer symbols and fixed keys over prose: `lv` for last verified commit, `head` for current commit, `gen` for generated date, `st` for status, `val` for validation, `next` for next step.
- Compress repeated names through aliases and dictionaries instead of restating full paths, tags, or subsystem names.
- Preserve enough semantic labels for Codex to expand the record into normal Markdown on request.
- Prefer semantic compression over text compression: preserve relationships, responsibilities, entry points, data flow, and dependency edges before preserving wording.

Recommended record types:

```text
@fresh id=FRESH-001 lv=<hash> head=<hash> gen=<date> st=<fresh|partial|stale> verify=<aliases>
@path <alias>=<path>
@focus id=ACTIVE-001 c=H :: <active work>
@handoff id=HANDOFF-001 c=H :: state=<now>; next=<step>; val=<signal>
@fact id=FACTS-001 c=H :: <stable fact>
@dec id=DEC-001 c=H :: <decision>
@constraint id=CONSTRAINTS-001 c=M :: <constraint>
@node id=<STABLE-ID> c=<H|M|L> stale=<reason|none> lvl=<L1-L5> fid=<lossless|lossy> imp=<1-100|H|M|L> vol=<H|M|L> cost=<H|M|L> files=<aliases> deps=<ids> usedby=<ids> :: <semantic summary>
@rel from=<id> to=<id> kind=<depends|uses|owns|feeds|validates|blocks>
@page id=<PAGE-ID> load=<ids> skip=<ids> trigger=<task-or-file-pattern>
@file id=FILEMAP-001 c=H path=<alias> role=<responsibility>
@validation id=VALIDATION-001 c=M cmd=<alias-or-command> :: <result or known use>
@coverage id=COVERAGE-001 c=M files=<count|?> docs=<count|?> pct=<%|?> :: <notes>
@stat id=STATS-001 ratio=<n:1|?> avgcost=<H|M|L|?> update=<duration|?> :: <memory metrics>
@chg date=<yyyy-mm-dd> tags=<tag,tag> files=<aliases> commit=<hash|Uncommitted> remote=<remote|Not-confirmed> :: <change>
@arch id=ARCH-001 c=H area=<name> deps=<aliases> :: <architecture note>
@open id=OPEN-001 c=M :: <unresolved item>
@archived id=ARCHIVE-001 c=H :: <compacted older history>
```

Expansion rules:

- When the user asks for a readable summary, expand only relevant `CCF/1` records into normal Markdown.
- When updating compressed files, edit the smallest matching record set and preserve unrelated records byte-for-byte when practical.
- If a record becomes too dense to understand, split it into multiple records with related IDs instead of adding paragraphs.
- Keep a readable root `CondensedContext.md` small by limiting it to freshness, focus, handoff, pointers, open threads, and the last 5-7 changes. Put complete `CCF/1` records in `CondensedContext.CCF1`.
- Do not use opaque binary, base64, gzip text, or private encodings. Codex should be able to inspect and modify the file directly.

## Compression Triggers

Use readable Markdown until one or more hard thresholds are met:

- `CondensedContext.md` exceeds 250 lines.
- Repeated sections exceed 40% of the file.
- Archived history exceeds 25 entries.

When any threshold is met:

- Keep root `CondensedContext.md` readable.
- Move full semantic records to `CondensedContext.CCF1`.
- Preserve the latest 5-7 meaningful changes in the root file.
- Keep older history, semantic graph records, file maps, dependency edges, paging records, coverage, metrics, and archived changes in the sidecar.

If the user explicitly asks for maximum compression before a threshold is met, use the root-plus-sidecar layout anyway and record that decision.

## Semantic Memory Model

Use semantic compression to store the meaning of the repository, not a shorter copy of prose:

- Preserve architectural relationships over isolated summaries.
- Represent subsystems as `@node` records with responsibilities, entry points, files, dependencies, downstream users, confidence, importance, volatility, and expansion cost.
- Represent relationships explicitly with `@rel` records when the dependency matters for staleness, paging, or reasoning.
- Represent retrieval plans with `@page` records so Codex can load only relevant memory for a task.
- Use source code as the final authority; compressed memory is a routing and reasoning layer.

Compression fidelity:

- `fid=lossless` keeps all important implementation details in compact form and is appropriate for active or risky areas.
- `fid=lossy` keeps architectural intent and relationships only and is appropriate for stable or rarely edited areas.
- Increase fidelity for high-importance, high-risk, or high-expansion-cost areas.
- Decrease fidelity for experimental, low-importance, or easy-to-reconstruct areas.

Compression levels:

- `lvl=L1`: semantic architecture graph; highest-level relationships and subsystem map.
- `lvl=L2`: subsystem summaries; responsibilities, dependencies, entry points, integration points.
- `lvl=L3`: file summaries; roles and important exported APIs.
- `lvl=L4`: symbol summaries; functions, classes, interfaces, schemas, or commands.
- `lvl=L5`: raw source; read only when compressed memory cannot answer safely.

Always start at the highest practical compression level. Expand downward only for the subsystem, file, or symbol needed for the current task.

## Dependency Graph And Paging

- Use dependency metadata to decide what context to load, refresh, or invalidate.
- When a changed file maps to a `@node`, refresh that node and inspect `@rel` edges to mark dependent nodes stale when their behavior may be affected.
- For a task scoped to one subsystem, load its `@node`, direct dependencies, direct users when behavior changes outward, relevant `@page` rules, and validation records.
- Avoid loading unrelated subsystems even when they are nearby in the repository tree.
- If dependency edges are unknown, add an `@open` item or low-confidence `@rel` instead of inventing certainty.

Scoring guidance:

- `imp` is importance to architecture or user-facing correctness.
- `vol` is expected change frequency based on recent edits and known project churn.
- `cost` is expansion cost: how much source reading is needed to reconstruct details.
- High `imp` plus high `cost` should stay more detailed and less lossy.
- High `vol` should be refreshed more often and may need lower compression while active.
- Low `imp`, low `cost`, or high experimental churn can be compressed aggressively.

## Updating Rules

- Update CondensedContext after each meaningful repository change, not after every tiny edit.
- Keep entries compact: one row or bullet should usually be enough.
- Treat CondensedContext as a memory index, not a transcript.
- Record durable facts: current focus, handoff state, decisions, constraints, file responsibilities, behavior changes, migrations, validation status, unresolved questions, and follow-up work.
- Avoid dumping transcripts, long diffs, generated logs, full command output, or information already obvious from the code.
- Preserve user-written notes and previous entries unless the user explicitly asks to rewrite them.
- Add tags in the `Tags` column, such as `[auth]`, `[ui]`, `[deploy]`, `[schema]`, `[tests]`, or `[docs]`.
- Keep the newest and most important information near the top sections. Use `Changes` for recent event history, not the main summary.
- If a change is not committed yet, write `Uncommitted` in the `Commit` column.
- If a change was committed but not known to be pushed, write the commit hash and `Not confirmed` in the `Remote` column.
- Prefer readable markdown: short wrapped paragraphs, clear headings, bullets, and tables instead of giant single-line blocks.
- Give major sections stable `Context ID` values so future updates can target them without rewriting unrelated content.
- Add a brief `Confidence` note to sections where verification state matters, such as `Verified against commit <hash>` or `Needs verification after <change>`.
- Separate durable knowledge from ephemeral work. Keep architecture, decisions, project goals, and conventions stable; let `Current Focus`, `Handoff`, `Changes`, freshness, and open threads change frequently.
- In compressed mode, prefer `CCF/1` records over readable bullets even when the result is less pleasant for humans.

## What To Keep

- Keep: durable decisions, architecture notes, important file paths, current feature state, validation commands/results, known environment limits, user preferences that affect future work, and open risks.
- Skip: obvious code details, generated files unless they matter, transient debugging attempts, raw logs, dependency install noise, and repeated summaries of the same fact.
- If CondensedContext and the code disagree, trust the code first, then update CondensedContext as stale or corrected.

## Work-Safe Memory

Do not record secrets, credentials, customer data, private employee information, proprietary business strategy, or sensitive incident details in CondensedContext files.
Summarize technical architecture and development state only.

When a sensitive source file, incident, customer workflow, or business detail affects engineering work:

- Record only the technical shape needed for future development, such as component names, integration boundaries, validation commands, or a generic risk.
- Replace sensitive specifics with neutral labels, such as `customer data flow`, `private config`, `incident follow-up`, or `restricted vendor integration`.
- Do not preserve raw excerpts, identifiers, names, tokens, account details, logs, secrets, or private strategy.
- If useful context cannot be retained safely, add an `Open Threads` or `@open` item telling future agents which source area needs re-reading with care.

## Coverage And Metrics

- Track coverage only when it helps future agents avoid unnecessary scanning.
- Keep coverage compact, such as indexed directories, missing areas, and files that still need verification.
- Record simple repository metrics when useful: files indexed, context documents present, last context update, and coverage percentage if known.
- Do not fabricate metrics. Use `Unknown` or omit them when the repository has not been scanned enough.

## Consistency Checks

Before saving updated context, verify the parts you touched:

- Referenced files and directories still exist.
- Referenced commands are still plausible from project files.
- Stored commit values match the intended git state.
- Sections that mention changed files have been refreshed or marked stale.

If checks fail, mark only the affected section stale and add the smallest useful next step to `Handoff` or `Open Threads`.

## Compaction

- If CondensedContext grows beyond about 150-250 lines, compact it before adding more routine history.
- Preserve `Context Freshness`, `Current Focus`, `Handoff`, `Stable Facts`, `Decisions`, `Known Constraints`, `File Map`, `Validation Memory`, `Coverage`, and `Open Threads`.
- Summarize older `Changes` rows into `Archived History` by topic or milestone.
- Do not delete commit hashes, pushed branch notes, unresolved risks, or user-authored decisions during compaction.
- If compacting would make durable sections too vague, move durable detail into layered files under `docs/context/` and link them from the root context.

## Commit And Push Tracking

When the user commits or asks Codex to commit:

1. Update CondensedContext before committing so the memory file is included in the commit when appropriate.
2. After committing, get the commit hash with `git rev-parse HEAD` or `git log -1 --format=%H`.
3. Replace relevant `Uncommitted` entries with the commit hash.
4. If this hash update creates a new working tree change, ask the user whether to amend the commit or leave the context hash update for a follow-up commit.

When the user pushes or asks Codex to push:

1. Confirm the push result when possible.
2. Mark relevant rows' `Remote` value with the remote and branch, such as `origin/main`.
3. If the push cannot be confirmed, keep `Not confirmed`.

When reviewing an existing repository:

- If recent commits are missing from CondensedContext, add concise rows for the durable changes only.
- If a row has a commit hash but no remote, check whether the commit exists on an upstream branch when the user asks for push status.
- Do not rewrite old history just to normalize style unless the user asks.

## Handoff And Validation

- Keep `Handoff` current before every final response after substantive work.
- Use `Last known state` for what is true now.
- Use `Next useful step` for the smallest concrete continuation.
- Use `Validation` for the best available signal, such as `npm test passed`, `typecheck failed in src/app.ts`, or `not run`.
- Update `Validation Memory` when a command becomes the known good way to check the project.
- Record failed validation only when it changes future behavior or leaves an open risk.

## User Preferences

- Record durable user preferences only when the user states them clearly or repeats them.
- Prefer concrete preferences, such as commit style, deployment target, framework choice, naming convention, or design constraint.
- Do not infer personal or sensitive preferences from one-off behavior.

## Before Final Response

- Make sure CondensedContext reflects the work completed in the turn.
- Update `Handoff` with current state, next step, and validation.
- Mention whether the CondensedContext file was created or updated.
- If tests or validation were run, record only the useful result, such as `npm test passed` or `validation not run`.