# dvn skill invocation packet Skill: public/immutable-reports Status: CURRENT Age: 4 seconds; source check: verified - devin-thomas/skills @ dce5977166216e8e88fcf56b6b53c76aaf91be5c; verified 2026-10-24T06:01:45.225Z Main source: immutable-reports/SKILL.md Main Git blob: 596806b76274557016a0ee521d4ec3217bce8425 --- name: immutable-reports description: Preserve implementation plans, their design decisions, and verification walkthroughs as numbered, append-only Markdown snapshots with a synchronized project ledger. Use to initialize a reports ledger, record or revise a plan, preserve approval or execution evidence, record partial or failed work, reconcile a ledger, or audit historical reports in any agent harness. --- # Immutable Reports Preserve what was proposed, authorized, attempted, and verified without rewriting earlier records. Use project files, user-provided text, or available user-facing artifacts as inputs; no special artifact filename or agent workspace is required. ## Contract - Freeze each complete snapshot when it is published into the ledger, even before a Git commit. Prepare editable drafts outside the final snapshot directories. - Add a new numbered snapshot for a revision or correction. Preserve earlier snapshot contents and paths, including when their status later changes. - Keep `reports/INDEX.md` as the mutable navigation and current-status view. Support status changes with linked evidence; do not change snapshot frontmatter. - Treat the full ledger-relative path as the report identity. Number plans and walkthroughs independently; `plans/001-...` and `walkthroughs/001-...` differ. - Record only approval already given and results supported by observations. Recording a plan does not authorize its implementation. - Use the current environment's permitted file or repository tools. No particular model, harness, shell, runtime, Git host, private account, or sibling skill is required. Git commits and remote publication follow the task's existing scope. This is an append-only working convention. It does not make writable storage tamper-proof. State what historical baseline an integrity audit actually checked. Before creating or reconciling reports, read [the ledger format](references/ledger-format.md). Use the relevant templates: [index](assets/INDEX.md), [plan](assets/plan.md), [walkthrough](assets/walkthrough.md), and [project rule](assets/project-rule.md). ## 1. Locate and inspect 1. Resolve the intended project root from the task and existing project context. Reuse its established ledger location; default to `reports/` for a new ledger. If multiple projects are equally plausible, ask which one before writing. 2. Inspect the project instructions, index, existing snapshots, and available history. Preserve existing layout, numbering, and historical metadata. 3. Determine the requested operation. Keep an audit read-only unless repair is requested. A one-time snapshot does not require a persistent instruction edit. 4. Identify the available write capability. If durable writes are unavailable, provide the complete proposed report and index delta, and state that neither was saved. Do not claim initialization, integration, or recording succeeded. ## 2. Initialize or adopt For a new ledger, create only the missing `plans/`, `walkthroughs/`, and `INDEX.md` beneath its root. Start the index from the supplied template. For an existing ledger, inspect contents before writing. Preserve custom sections, historical rows, snapshot bytes, and links. Add missing compatible structure; do not replace an existing index with the empty template. A healthy second initialization makes no changes. When asked to establish an ongoing project rule, merge the supplied rule into the applicable project instruction file if the task covers that edit. Choose the file the project actually uses; do not require or create a particular harness's instruction filename. Avoid duplicate rules and verify the resulting content. Direct skill use remains valid without persistent integration. Complete setup only after reading back the directories and index. Report persistent instruction integration separately, including when it was unnecessary or unavailable. ## 3. Prepare a snapshot Capture each completed plan version, substantive revision, approval transition, or implementation/verification milestone being recorded. Do not wait for `implementation_plan.md` or `walkthrough.md` to appear, and do not record every intermediate drafting edit. For a plan, include scope, decisions, intended changes, acceptance criteria, and known constraints. Use `draft` unless existing authorization or a project record supports `approved` for this exact version. Cite that evidence. Do not ask the user to approve again merely to record approval already given. For a walkthrough, include work performed, checks and their actual results, evidence, remaining work, and limitations. Use `status: recorded` and an honest `outcome`: `passed`, `partial`, `failed`, `blocked`, or `not-run`. A walkthrough can be useful even when the task is unfinished. Keep each snapshot understandable on its own. Copy the relevant user-facing content into the report, identify its source, and link supporting evidence. Do not substitute a link to an ephemeral agent artifact for the report body. Use project-relative paths or stable revision links where possible; identify evidence that is unavailable or mutable. Exclude credentials and internal agent reasoning. Recording evidence does not imply that every linked artifact's bytes were preserved. ## 4. Publish and reconcile 1. Serialize ID allocation, snapshot creation, and index reconciliation through one designated ledger writer or an equivalent conditional transaction. Parallel agents can prepare content outside the ledger. Exclusive creation of one filename alone does not prevent duplicate IDs with different topic slugs. 2. Read the latest snapshots and index. Within the selected type, allocate one more than the greatest known numeric ID, including IDs reserved by historical index rows. Start at `001`, pad to at least three digits, and continue with `1000` after `999`. Do not fill gaps or reset numbering on a new date. 3. Choose a safe topic slug, fill all template values, and check frontmatter, references, and intended destination before publishing. Use creation that rejects an existing destination. Never use an overwrite or force option. 4. Read back the new snapshot. Immediately add its index row once, using a link relative to the ledger root. Preserve unrelated rows and concurrent changes. 5. Apply only status transitions supported by the new evidence: - A new plan can supersede the exact earlier unexecuted versions it explicitly replaces. An already executed plan remains part of the execution history. - Mark a plan `executed` only when a linked walkthrough demonstrates completion of that plan's scope and acceptance criteria. A `passed` check on one subset, a different revision, or a partial/failed attempt is insufficient. - For approval-only changes, create a new approved snapshot containing the plan and approval evidence, linked to the previous draft. Keep the draft unchanged. 6. Verify the snapshot, unique identity, exactly one corresponding index row, resolving links, justified state changes, and unchanged prior snapshots. When appropriate, commit the report and index together under the repository's existing workflow; saving reports does not itself authorize pushing remotely. If coordinated, non-overwriting publication is unavailable, keep the prepared content outside the ledger and identify the blocked write. Do not weaken the contract to claim completion. ## 5. Recover or audit For a complete snapshot missing from the index, verify it and add the missing row; do not recreate or edit the snapshot. For an index row with no snapshot, inspect history and backups. Preserve the row and reserve its ID; never invent the missing report's contents or silently remove the evidence of a gap. For a partial write, conflicting IDs, an interrupted update, or a suspected changed historical report, preserve available evidence and report the exact discrepancy. Use an additive correction or a verified recovery under the task's authorization. Do not silently renumber, delete, rewrite, or backdate reports. Audit structure, metadata, numbering, links, status evidence, and consistency between snapshots and index. Compare older bytes against a known earlier commit, trusted copy, or digest when available. Without that baseline, report structural consistency and the integrity checks that remain unverified. Do not repair an audit finding without repair scope. ## Completion Return the new report paths, index path, source/version relationships, and the recorded outcome. Distinguish saved locally, committed, and remotely published only when those actions actually occurred. If a snapshot exists but index reconciliation failed, report that partial state and the exact remaining repair; the recording operation is not complete until both agree. --- Supporting source: immutable-reports/references/ledger-format.md Git blob: 175319d739debbab3404de2cae44c154de4cc6d1 # Ledger format ## Contents - [Layout and identity](#layout-and-identity) - [Metadata](#metadata) - [State and evidence](#state-and-evidence) - [Index](#index) - [Compatibility and recovery](#compatibility-and-recovery) ## Layout and identity Use these defaults for a new ledger; honor an existing project contract: | Artifact | Path from the project root | | --- | --- | | Mutable index | `reports/INDEX.md` | | Plan snapshot | `reports/plans/--.md` | | Walkthrough snapshot | `reports/walkthroughs/--.md` | Use independent ascending integer sequences for plans and walkthroughs. Format IDs as quoted strings with at least three digits. Allocate from the maximum known ID in that type's files and index, not the file count. Preserve gaps and reserved historical IDs. Never allocate the same type/ID to different filenames. Use a short lowercase hyphenated topic slug containing only ASCII letters, digits, and single hyphens; start and end with a letter or digit. Do not accept path separators, traversal segments, or an absolute path as a slug. Use the project or user's known timezone for the filename date. If neither is known, use UTC and disclose that assumption. Optional `recorded_at` must include an explicit UTC offset or `Z`. Use the recording date for a new retrospective report; state the earlier event date in its body instead of backdating. Reference another report by its full path relative to the ledger root, for example `plans/003-2026-10-23-cache-policy.md`. Bare IDs are ambiguous across types. Metadata paths always use this ledger-relative form; Markdown body links must instead resolve from the file that contains them. ## Metadata Keep the original five required fields. Add `outcome` to new walkthroughs. | Field | Rule | | --- | --- | | `type` | `implementation-plan` or `walkthrough` | | `id` | Quoted numeric ID matching the filename | | `date` | Quoted `YYYY-MM-DD` matching the filename | | `title` | Nonempty quoted descriptive title | | `status` | State asserted when the snapshot was recorded; never edit later | | `outcome` | Required for new walkthroughs; omit from plans | | `recorded_at` | Optional timestamp with timezone | | `supersedes` | Optional list of exact earlier report paths replaced or corrected | | `plans` | Optional list of exact plan paths whose work a walkthrough addresses | Use valid YAML, quote IDs and date-like values, and escape title strings correctly. Omit unused optional fields rather than leaving template tokens. Preserve extra metadata already required by the project. For new plans, use `draft` or `approved` at recording. If a later report changes their current state, reflect that in the index while retaining the original frontmatter. For new walkthroughs, use `status: recorded`; this means an observation was preserved and makes no completion claim. Example plan revision: ```yaml --- type: implementation-plan id: "004" date: "2026-10-23" title: "Cache policy with explicit invalidation" status: approved supersedes: - "plans/003-2026-10-23-cache-policy.md" --- ``` An approved snapshot must include the applicable approval evidence in its body. If approval covers only the earlier version and the revision changes scope, use `draft` for the new version. Example incomplete walkthrough: ```yaml --- type: walkthrough id: "002" date: "2026-10-23" title: "Cache invalidation implementation and checks" status: recorded outcome: partial plans: - "plans/004-2026-10-23-cache-policy.md" --- ``` ## State and evidence Use these current plan states in the index: | State | Required basis | | --- | --- | | `draft` | A proposed version without applicable recorded approval | | `approved` | Existing user authorization or project approval covering that version | | `executed` | A linked walkthrough covering the plan's scope and acceptance criteria | | `superseded` | An explicit replacement of an unexecuted plan version | An approved successor supersedes the earlier draft; it does not rewrite the old draft's frontmatter into an approval record. Keep prior executed versions marked executed when subsequent work evolves the design. Use a body link to relate a new plan to an executed predecessor rather than marking that predecessor unexecuted or superseded. Record walkthrough outcomes against the stated walkthrough scope: | Outcome | Meaning | | --- | --- | | `passed` | All checks needed for that stated scope completed successfully | | `partial` | Some work or required checks remain; document any individual failures | | `failed` | Attempted work or a required check failed; describe remaining coverage | | `blocked` | A missing capability, dependency, or access prevented useful completion | | `not-run` | No execution or verification was performed; the report records that fact | Choose the outcome that best describes the milestone and enumerate the actual per-check results. Do not use `passed` when a required check was skipped. A narrowly scoped walkthrough can pass without completing its parent plan. A `plans` link associates evidence; it does not automatically mark any plan executed. A `supersedes` link records replacement or correction; explain what changed. Use supersession within a report type, target an older report, and avoid cycles. Do not treat a matching title, latest date, or greater ID as evidence that one report replaces another. Prefer evidence preserved within the ledger or at an immutable source revision. For an approval given in conversation, preserve its relevant wording or faithful summary, date, and context in the new snapshot; use a stable conversation reference only if actually available. Never invent an approval, URL, timestamp, commit, test result, or source identifier. If new evidence retracts a completion claim or corrects an earlier walkthrough, write a new walkthrough referencing the corrected report with `supersedes`. Explain which plan claims are affected. Preserve the original report. Annotate the plan's index status with the discrepancy and corrective report; do not silently continue treating contradicted evidence as current or fabricate a new approval state. Resolve any remaining ambiguity explicitly. ## Index Use the supplied index template for a new ledger: - **Plans:** ID, Date, Current status, Title, File, Status evidence. - **Walkthroughs:** ID, Date, Outcome, Title, File. Keep a single row per report path. A plan row initially cites its own snapshot. A later change to its current status cites the newer report supporting the change. Keep all earlier report rows accessible. For a corrected walkthrough, preserve both rows and annotate the earlier row's Outcome cell with a link to the corrective report, for example `partial; corrected by 003`, with `003` linked to `walkthroughs/003-2026-10-24-correction.md`. Retain its originally recorded outcome rather than presenting the later result as what happened then. Escape pipes and line breaks in Markdown table text. Links in `INDEX.md` resolve from the ledger root. Existing column arrangements may remain in use if they convey the same evidence and preserve the project's historical information. The index is editable, but it is not an independent authority for changing what a snapshot said. A status that differs from its snapshot needs linked later evidence. Never update the entire index from a stale cached copy. ## Compatibility and recovery Adopt an existing ledger in place. Do not rename old files, reformat frontmatter, renumber reports, or add missing fields to frozen snapshots. New reports follow this contract; classify older schema differences as legacy records. Read an existing walkthrough's `status: executed` as its historical claim. If it has no outcome field, show its recorded status and note that the outcome was not separately recorded; do not manufacture a passed result. When an older index already reports current state, retain it and identify unsupported claims as unverified until evidence establishes them. Coordinate writes across the whole ledger, including its shared index. For shared files, use one designated writer with no competing writers, or the environment's suitable lock. For a repository API, a conditional commit/ref update can provide equivalent coordination if it detects a changed base and never replaces existing reports. Keep lock mechanics out of report identity. Branches and independent worktrees do not share a numbering lock. Before integration, inspect the combined ledger for ID and index conflicts. Resolve unpublished allocations before publishing. If both conflicting snapshots were already published, preserve their paths and record the collision for an explicit additive reconciliation; do not silently renumber one of them. A retry after a snapshot succeeded but its index update failed must reuse the existing verified snapshot and add only its missing row. A wholly interrupted or partial file is not a valid report: retain it as recovery evidence until its provenance and the authorized recovery are established. Do not use a template to invent missing historical content. Restore missing historical bytes only from a verified prior copy or revision when recovery is in scope. Treat absent or inconsistent history as an explicit audit finding. Never claim that a present-day structural check proves historical immutability.