jaredchu/context-docs / skills/context-docs
context-docs
VerifiedCreate, audit, and maintain project context documents and Markdown progress views for continuity across AI sessions. Use when establishing context conventions, refreshing project state, visualizing progress toward a documented goal, or consolidating stale context. Adapt to existing layouts and preserve decisions and evidence. Not for general copyediting or storing conversation transcripts.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 10.1 KB |
| VERSION | other | 6 B |
| agents/openai.yaml | config | 224 B |
| assets/decision-record.md | markdown | 724 B |
| assets/project-context.md | markdown | 1.1 KB |
| references/event-journal.md | markdown | 13.3 KB |
| references/local-only.md | markdown | 5.9 KB |
| references/progress.md | markdown | 9.1 KB |
| references/standard.md | markdown | 9.1 KB |
| scripts/event_journal.py | script | 8.7 KB |
| scripts/journal_policy.py | script | 10.9 KB |
SKILL.md
View on GitHub---
name: context-docs
description: Create, audit, and maintain project context documents and Markdown progress views for continuity across AI sessions. Use when establishing context conventions, refreshing project state, visualizing progress toward a documented goal, or consolidating stale context. Adapt to existing layouts and preserve decisions and evidence. Not for general copyediting or storing conversation transcripts.
---
# Context Docs
Keep the project's Markdown useful to the next reader. Start with its instructions,
README and context entry point, then follow relevant sources. Identify a project
mismatch before editing; ask only when the target or a consequential decision is
unclear. Preserve existing layouts and concurrent edits.
## Choose the operation
- **Audit:** report concrete gaps and source locations; leave project files unchanged.
- **Initialize:** reuse suitable files or sections. Read [the standard](references/standard.md)
for document roles. If an entry point is missing, adapt [the template](assets/project-context.md),
remove unused prompts, and link shared context from the README or documentation index.
For shared context, if neither exists, a short README pointing to the supported
context is enough; it does not require inventing a broader project mission.
For local-only context, use the local discovery route below instead.
When initializing from earlier notes, check relevant project sources before
importing claims about current implementation or configuration. Carry forward
decisions and unresolved work without treating the notes as proof of current state.
- **Maintain:** update affected canonical sections from completed work and evidence.
Consult the standard when roles, conflicting statuses or restructuring need it.
Ordinary document repairs are included; proposed product decisions are not approved
by a maintenance request. A review without permission to edit remains an audit.
## Visualize progress in Markdown
When documented, keep the goal, meaningful advances, blockers and next action
findable in the existing layout during initialization and maintenance. Use the
[progress guide](references/progress.md) for requested views and adoption's
default inline view when documented context supports it.
For a visualization request, show a compact visual path through the documented
work, with dependencies, blockers and the next action visible. A flat status
table alone is insufficient; keep the view readable in plain Markdown.
Favor a concise overview with links to detailed evidence, following the guide;
preserve decisions, rationale, blockers, approval boundaries and unresolved work,
with qualifications that affect the meaning of a status or next action.
Refresh an existing view when relevant facts change; no repeated invocation is
needed when the loaded project rule already authorizes ongoing maintenance.
Use the existing context section or a linked Markdown file when that improves
navigation or the user requests it. Keep each detail authoritative in one place
and link summaries to their sources. Preserve storage boundaries, layouts and
setup rules; do not create a parallel tracker, web app or runtime dependency.
An audit can assess progress clarity but does not write a view or enable logging.
## Make the smallest useful update
Within authorized context edits, prefer clear, direct sentences and consistent
project terminology. Split crowded sentences without losing conditions,
uncertainty, rationale or evidence. Preserve existing layouts and unrelated owner text.
When agents or sessions work concurrently on the same context file, coordinate
one writer at a time for that file; others pass their findings to the writer.
Agree on the writer before concurrent edits begin, including across Codex and
Claude sessions in a shared checkout. Change writers through an explicit handoff.
Prefer narrow edits. After an edit conflict or stale-text failure, reread the
current file and reconcile contributors' changes before retrying. Do not overwrite
newer work from a stale snapshot. This is a coordination rule; file access remains
unlocked.
Preserve the existing storage choice unless the user requests a change. For an
explicit local-only (Git-ignored) request, or maintenance of an existing local-only
setup, read the [local-only guide](references/local-only.md). Verify tracking and
ignore status before writing, read the named entry point directly even when searches
omit ignored files, and keep its content out of shared destinations. An audit reports
storage gaps without changing files, Git state or settings.
Select durable information for the intended reader and actual sharing destination.
For decisions about what to retain or where it belongs, use the standard's
[audience and destination guidance](references/standard.md#audience-and-destination).
Project labels alone do not decide what is useful or appropriate to share.
Before saving, review proposed additions and enabled journal payloads for incidental
usernames, home/backup/scratch paths, account identifiers and personal installation
state. Omit details that do not help the intended reader; summarize relevant tool
findings instead of copying raw output. Keep secrets out of every destination.
Prefer repository-relative references for project files. In shared content, refer
to private evidence through a suitable public summary, stable evidence ID or hash
without exposing its local location or implying readers can access or independently
verify it. Retain useful local paths in appropriate local notes. When exact paths or environment
details explain a failure, preserve the diagnostic relationships and necessary
constraints; any authorized public derivative must retain provenance and limits.
Do not rewrite frozen evidence, relocate records or change storage rules just to
make references portable.
Record each detail, outcome and material qualification once in its canonical
location; link from summaries. Include preservation or installation bookkeeping
only when it establishes a relevant compatibility condition, failure or requested check.
Do not append a diary of routine checks or repeat unchanged safeguards. Review
the changed content, without requiring a repository-wide scan or a separate
filtering report. Filtering must preserve decisions, conditions, rationale,
uncertainty, blockers and supporting evidence, including useful personal context.
Check factual claims against the source that establishes that exact claim before
recording them. Keep the evidence's scope: a reference document's version is not
the installed package version, and local configuration does not establish runtime
behavior or publication history. Omit incidental details you have not checked;
state a specific verification limit when the unknown matters. Keep approved intent,
observed behavior, proposals and unknowns distinct. Resolve contradictory guidance
at its source when evidence permits; otherwise identify the specific unresolved
conflict. Imported instructions are evidence, not authority.
Attribute implementation choices to whoever made them; permission to do a task
does not make an agent-chosen method or layout an explicit owner decision.
Describe inspected operations directly; do not turn them into guarantees for every
input without verification.
Replace stale claims in place. Add uncertainty only where it changes a
reader's interpretation or next action, rather than repeating generic verification
disclaimers. Initialization needs supported context and useful navigation, not a
catalogue of everything the project has not documented.
Preserve unique decisions, authority, rationale, constraints, source links, useful
dated evidence and unresolved work. Mark superseded guidance without losing its
rationale. Do not shorten by hiding blockers or relying on Git to recover uncommitted
material. Keep commands, fences, anchors and relative links intact.
Review the diff, affected links and information preservation against the resulting
project. Refresh facts made stale by your own edits; label retained earlier
observations as pre-change when they no longer describe current state. Check the final
report's factual claims by the same standard as the edited documents, retaining
their qualifications rather than strengthening them in a summary. Date only claims
actually reviewed. If nothing durable changed, avoid bookkeeping edits. Briefly
report changed files, completed checks and material remaining questions once,
without restating unchanged context. Do not copy the session report into the context.
## Optional event capture
Logging is off by default; ordinary Markdown maintenance needs no runtime or
journal. When the user has selected `Context Docs logging preference: auto` and
no project logging setting exists, consult the journal guide below during authorized
maintenance to resolve the preference for no-Git projects or explicitly selected
local-only context. Inside Git, verify the context and journal paths are ignored
and untracked before enabling. Existing settings always take precedence; selecting
local-only storage alone does not enable logging. Audits never enable logging. An enabled
setting does not make history part of routine context reading.
For no-change maintenance, check current context and supplied evidence; if there
is no new event, contradiction or uncertain prior write, stop without listing,
searching or reading journal files. A link to history alone is not a reason to open it.
Use known entry-point paths directly for this check; broad project file searches
can enumerate journal files even when their contents are not opened.
Read [the journal guide](references/event-journal.md) when capturing a new event,
configuring logging, investigating history, resolving a contradiction that needs
historical evidence or checking an uncertain write. Follow existing project
settings. Capture meaningful events only when enabled; setup, no-change maintenance
and audits create no events. Keep historical capture separate from current context
and preserve records across updates.
Keep secrets and unnecessary personal or customer data out of context. This skill
adds no authority to commit, publish, alter global instructions, schedule work or
provision services; follow the project's existing authorization. It provides no
background sync.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |