jaredchu/context-docs / skills/context-docs
context-docs
UnverifiedCreate, 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 for document roles. If an entry point is missing, adapt the template, 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 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. 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. 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 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: 464k | 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: 464k | 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: 464k | 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: 192k | Updated | Claude CodeCodex | Verified | Install |