Skip to content

jaredchu/context-docs / evals/results/2026-09-28-journal-gap/claude-audit/.claude/skills/context-docs

context-docs

Verified

Create, audit, and maintain project context documents for continuity across AI sessions. Use when establishing a context-docs convention, refreshing project state after work, or consolidating stale or growing context files. Adapt to existing layouts and preserve decisions and evidence. Not for general copyediting or storing conversation transcripts.

FileKindSize
LICENSEother1.0 KB
SKILL.mdskill md4.5 KB
VERSIONother6 B
agents/openai.yamlconfig224 B
assets/decision-record.mdmarkdown724 B
assets/project-context.mdmarkdown935 B
references/event-journal.mdmarkdown7.0 KB
references/standard.mdmarkdown5.3 KB
scripts/event_journal.pyscript8.7 KB

references/standard.md

View on GitHub
# Context Docs standard

Version: 0.1.0 (experimental).

This is a convention for project knowledge, not a required directory tree or file
format beyond readable Markdown. Use the project's established terms and map
them to these meanings. Do not introduce metadata fields that nobody will use.

## Document roles

| Role | Answers | What belongs here |
| --- | --- | --- |
| Entry point | Where should a new reader start? | Purpose, scope, canonical links and reading order |
| Current state | What is true now? | Verified state, active work, blockers and next actions |
| Decisions | What was chosen, by whom, and why? | Status, authority, rationale, consequences and sources |
| Open questions | What still needs an answer? | Uncertainty, impact and the evidence or decision needed |
| Procedures | How is work performed? | Applicable steps, prerequisites and relevant verification |
| Historical evidence | What happened, and what supports it? | Dated observations, evaluations and superseded rationale |

A small project may keep the first four roles in one `context.md`. An established
project may use `docs/README.md`, several registers, and runbooks. Neither is more
compliant by filename. Create a separate file when it improves navigation or
ownership, not to fill every row of this table.

The entry point should identify the project and its boundaries and link to
canonical details. Prefer repository-relative links for portable project docs.
Do not copy facts between unrelated projects to simulate continuity.

## Statements and authority

Keep these distinctions explicit when ambiguity could change what the next
person or agent does:

- **Observed:** supported by identified evidence, with an observation date when
  freshness matters. Say whether the evidence is code, configuration, a test or
  live state; those are different claims.
- **Approved:** a decision made by someone with authority for that project.
  Retain the authority/source and rationale. An assistant suggestion is not
  approval, and implementation alone need not establish owner approval.
- **Proposed:** a suggested future action or decision, not current policy.
- **Unknown:** unresolved information or conflicting sources, with the next
  useful check when known.
- **Superseded:** earlier guidance replaced by identified newer guidance.
  Preserve rationale or historical evidence that remains useful.

These are semantic categories, not compulsory labels on every sentence. Preserve
an existing equivalent status vocabulary. Implementation state and decision
status are separate: an approved change can remain unimplemented, and deployed
behavior can disagree with an approved decision.

When code and docs differ, correct claims about what the code does while keeping
the decision discrepancy visible. Do not silently rewrite approved intent to
match implementation, or declare runtime behavior from code alone. If a needed
source is inaccessible, state the verification limit instead of inventing it.

## A maintenance cycle

Maintain context after meaningful changes to behavior, configuration, decisions,
procedures or project status, or when the user requests a review. Routine work
that adds no durable information needs no new note.

1. Read the entry point and affected canonical sections.
2. Identify the new evidence and which claims it changes.
3. Update current state and preserve decision status and source references.
4. Consolidate duplication and move details only where that helps navigation.
5. Check the diff, links, pending work and information preservation.

Treat dates as evidence boundaries. Updating one configuration fact does not
justify stamping an entire unreviewed runbook as current. Record a command's
scope and result when useful; omit repetitive command logs.

## Controlling growth

Keep current context focused on the next reader's decisions. Replace resolved
status items rather than appending a daily diary. Keep detailed evidence in one
canonical location and link from summaries.

Word counts are signals, not deletion quotas. Split an entry point when unrelated
detail makes it hard to navigate. Consolidate repeated facts only after checking
that their qualifications agree. A short file that loses a constraint is worse
than a longer accurate file.

Use Git for edit history where available. Retain important decision rationale,
evaluation evidence and unresolved work in readable documents even when Git
exists. Mark archived guidance as historical and keep inbound links useful.
Never delete uncommitted material on the assumption that Git can recover it.

## Minimal adoption

For an existing project, map its files to roles and fix the most consequential
gaps in place. Do not migrate directories just to match an example. For a new
project, start with [one context document](../assets/project-context.md) linked
from the README. Add a [decision record](../assets/decision-record.md) only when a
decision warrants its own rationale. No manifest, database or index is required.

## What this standard does not provide

Markdown/Git does not automatically resolve concurrent edits, enforce access
permissions, verify facts, or run maintenance. Agents must inspect edits and use
available evidence; Git helps review and recovery. Cross-device synchronization
uses the user's existing repository workflow. Any future search service should
preserve source paths and revisions and remain separable from the originals.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall