Update docs

Research Documentation Maintenance

Purpose

Keep research documentation current with dated supersession and historical preservation.

When To Use

Use when docs, notes, reports, ledgers, run records, public summaries, or workflow guidance have drifted from the current project state.

This skill owns documentation planning, documentation edits, dated supersession, historical preservation, and post-edit audit.

Required Inputs

• {{PROJECT_NAME}}
• {{AS_OF_DATE}}
• {{DOCUMENT_ROOT}}
• {{SEED_FILES}}
• {{CANONICAL_DOCS}}
• {{EVIDENCE_SOURCES}}

Optional Inputs

• {{ARCHIVE_AREAS}}
• {{PLANNER_OUTPUT}}
• {{DIFFS_OR_PATCHES}}
• {{MERGE_OR_HANDOFF_CRITERIA}}
• {{SHARED_RESEARCH_CONTRACT}}
• {{EXCLUSIONS}}
• {{STYLE_GUIDE}}
• {{AVAILABLE_TOOLS}}
• {{SAFETY_PRIVACY_OR_RELEASE_CONTEXT}}
• {{OUTPUT_LOCATION}}

Authority Order

Use {{SHARED_RESEARCH_CONTRACT}} when supplied. Otherwise apply this order by claim type:

1. Explicit user instructions, release constraints, safety constraints, and local project conventions.
2. Raw or near-raw project evidence for project-state claims.
3. Primary external sources for external claims.
4. Reproducible analyses and transparent secondary sources that cite primary artifacts precisely.
5. Canonical current-state project documents and authority ledgers.
6. Dated archival records and historical notes.
7. Input reports, model outputs, comments, and prior narratives, treated as leads.
8. Maintainer judgment, labeled as judgment.

Raw project evidence includes run outputs, analysis tables, logs, commits, reports, notebooks, datasets, and source artifacts.

Tool And File-Access Assumptions

Use repository search, file editing, diff inspection, git history, link checks, formatters, tracker updates, and artifact lookup when available. If direct editing is unavailable, produce a patch plan with file paths, section names, replacement text, and validation steps.

If browsing, tracker updates, or document editing are unavailable, state that limitation and provide the closest actionable substitute. Run safety, privacy, misuse, security, or release checks when relevant to {{SAFETY_PRIVACY_OR_RELEASE_CONTEXT}}.

Write the plan, edit report, audit, or compact refresh to {{OUTPUT_LOCATION}} when supplied and artifact creation is available.

Handoffs

Upstream evidence may come from literature-review, report-arbitration, research-manuscript-audit, review-data-pipeline, paper-discovery, or user-provided project evidence.

Downstream artifacts are Documentation Refresh Plan, Documentation Edits, Documentation Audit, or Documentation Refresh.

This skill updates docs from accepted evidence. Retrieval, framing generation, report arbitration, draft audit, and pipeline audit stay with their owning skills.

Claim-Support Statuses

Use one status per substantive claim:

• Supported
• PartiallySupported
• ReasonableInference
• Ambiguous
• Overstated
• Unsupported
• StaleOrSuperseded
• Unverified
• Opinion

Document States

• CanonicalCurrent
• MixedCurrentAndHistorical
• ArchivalHistorical

Change Types

• PreserveAsRecord: keep dated observations, prior hypotheses, and old decisions that explain project history.
• SupersedeWithNote: preserve historically useful stale claims with dated replacement notes and links to current evidence.
• RewriteCurrentState: rewrite present-state claims to match current evidence.
• DeleteLowValue: remove material with low current value and low historical value.
• AddSection adds missing sections when they improve legibility, reproducibility, safety, or handoff quality.

Process

Choose the smallest pass that fits the documentation surface.

Planning Pass

Use first for medium or large refreshes.

1. Read seed files first.
2. Discover likely current-state docs, indices, reports, handoff notes, ledgers, and archival areas.
3. Classify each document as CanonicalCurrent, MixedCurrentAndHistorical, or ArchivalHistorical.
4. Extract important claims about results, interpretations, causal claims, active hypotheses, next steps, release guidance, and current state.
5. Compare claims against {{EVIDENCE_SOURCES}} and assign one claim-support status.
6. Track document state and change type separately from claim status.
7. Identify contradictions across current docs or between docs and evidence.
8. Recommend files to edit, files needing pointers, and files to preserve as historical records.
9. Produce an edit plan.

Execution Pass

Use after the planning pass or for small updates with clear evidence.

1. Update canonical current-state docs first.
2. Update mixed current and historical docs second.
3. Touch archival docs to preserve context, add a dated supersession note, or point to fresher canonical docs.
4. Preserve local terminology, structure, and author voice where possible.
5. Prefer one canonical current-state summary over duplicated status narratives.
6. Separate observations, interpretation, and next actions where the file structure allows.
7. Add or refresh safety, privacy, misuse, security, or release notes when the context calls for them.
8. Produce a file-level patch plan when direct editing is unavailable.

Audit Pass

Use after documentation edits and before merge, handoff, release, or publication.

Check:

• historical integrity
• freshness of current-state claims
• traceability to evidence
• reproducibility usefulness
• claim calibration using the shared status vocabulary
• separation of claim status, document state, and change type
• retention of negative or contradictory evidence
• cross-file consistency
• safety, privacy, misuse, security, or release hygiene where relevant
• removal discipline

Compact Refresh

Use when the documentation surface is small enough for one pass. Run planning, execution, and audit in one artifact.

Output Contract

Produce the applicable Markdown artifact.

Documentation Refresh Plan

1. Executive Summary
2. Document Inventory
3. Claim Triage
4. Canonical Update Set
5. Edit Plan
6. Open Unknowns

Documentation Edits

1. Changed Files Or Patch Plan
2. Key Edits
3. Evidence And Assumptions
4. Historical Preservation Notes
5. Remaining Follow-Ups

Documentation Audit

1. Verdict: Pass, PassWithFollowUps, or Fail.
2. Critical Issues
3. Major Issues
4. Minor Issues
5. Reproducibility Gaps
6. Risk Or Release Gaps
7. Minimum Patch Set

Documentation Refresh

1. Plan
2. Edits Applied Or Patch Plan
3. Self-Audit
4. Open Follow-Ups

Quality Gate

Before finalizing, verify:

• Historical records remain historically accurate.
• Current-state claims are tied to evidence or explicit uncertainty.
• Claim status, document state, and change type are separate.
• Safety, privacy, or release checks appear where relevant.
• Negative results, failed attempts, and contradictory evidence remain visible when they affect future decisions.
• Missing reproducibility metadata, safety results, operational details, and provenance are documented as missing.
• Tool, browsing, tracker, edit, and artifact claims match completed actions.