baseline-first-reconciliation

Files (9)

• SKILL.md
• baseline-first-reconciliation.md · references/
• candidate-artifact-parity.md · references/
• medication-out-of-window-exception.md · references/
• medication-stale-state-reconciliation.md · references/
• owner-corrected-adherence-analytics.md · references/
• runtime-reload-and-config-contract.md · references/
• standing-goal-completion-audit.md · references/
• temporal-authority-and-runtime-provenance.md · references/

SKILL.md (first lines)

# Baseline-First Reconciliation

## Purpose

Use this skill when a task sounds like **recover the original setup**, **restore after a merge/update**, **reconcile live and source**, **rollback**, **port pre-change work**, or **fix drift after migration**.

The failure this prevents is a plan that starts from today's symptom, patches one consumer, and then incorrectly describes that patch as recovery of the original system. Recovery requires provenance. A plausible fix is not proof of restoration.

## Core rule

```text
owner-designated temporal target → classify design vs implementation artifacts → pre-change inventory → current live probe → four-layer matrix → objective classification → minimal plan
```

Do not reverse this order. Do not write an implementation plan from a compacted conversation summary when a canonical design document, handoff, or source artifact exists.

## Temporal-authority gate

Before calling any artifact the recovery baseline, establish **which artifact the owner means to recover**. A GDoc, wiki, or design record can be canonical for intent while being an intentionally older baseline that predates source access, a merge, deployment, or the owner-designated last known working version.

1. Record the owner’s temporal boundary exactly: date, timezone, and wording such as “latest working version before <event>.”
2. Classify the document: `BASELINE-DESIGN`, `CANDIDATE-BUILD`, `RELEASE-MANIFEST`, `RUNTIME-EVIDENCE`, or `HISTORICAL-CLAIM`.
3. Search for actual artifacts at or immediately before that boundary: commit/tree, preserved worktree, manifest, source hash, and runtime/service evidence.
4. Prove both **provenance** (it belongs to the requested period) and **behavior** (it contains or demonstrates the expected contract) before naming a candidate `latest`, `working`, or `recovery-ready`.
5. If the owner-designated artifact is not located, say `LATEST OWNER-DESIGNATED ARTIFACT NOT LOCATED`. Do not silently substitute an older design doc, a convenient branch, or a compatible patch.

A branch name, commit date, file mtime, or historical “deployed” statement is a lead—not recovery authority. A direct live probe proves present behavior, not which historical artifact should replace it.

## Objective vocabulary

Classify the work before selecting actions:

| Objective | Meaning | What it is not |
|---|---|---|
| **RECOVERY** | Restore a known prior artifact or behavior whose identity and content are proven | A new fix that merely seems compatible with the old design |
| **RECONCILIATION** | Determine what survived, was omitted, drifted, contradicted, or was never transferred | A blind rollback or wholesale merge |
| **ROOT-CAUSE REPAIR** | Correct a directly reproduced current defect at its causal boundary | A workaround applied before the dataflow is traced |
| **NEW DESIGN** | Introduce behavior not present in the original contract | “Recovering” a desired behavior that never existed |

A task may contain more than one objective, but each objective must have its own lane, evidence, acceptance criteria, and gate.

## Mandatory procedure

### 1. Freeze the question before touching implementation

Write a one-line statement:

> “This investigation is [RECOVERY / RECONCILIATION / ROOT-CAUSE REPAIR / NEW DESIGN] of [scope]. It will change [x] and will not change [y].”

If the owner asks “what are you actually trying to do?”, stop implementation and answer this scope question first. Do not respond with a list of fixes whose relationship to the original goal is unclear.

### 2. Read the canonical artifact completely

Read the supplied Google Doc, design record, handoff, spec, pre-change report, or release manifest before relying on:

- compacted session summaries;
- another agent’s synthesis;
- file names or branch names;
- a previous “done/deployed” statement;
- the first obvious live symptom.

For Google Docs, use a full structural read that walks paragraphs **and tables**. Paragraph-only extraction can silently omit the actual contract, evidence ledger, status table, or acceptance criteria.

Record:

- document identity and URL/path;
- document date/version and update date;
- stated scope and explicit exclusions;
- source-of-truth claims;
- acceptance criteria;
- candidate/live/deployment status claims;
- known data gaps and contradictions.

### 3. Inventory the pre-change boundary

Identify the exact boundary named by the owner: merge, update, migration, deployment, or date. Before that boundary, inventory the relevant:

- documentation and design records;
- source files and tests;
- configuration/data schemas;
- candidate branches and commits;
- runtime hooks and entry points;
- state stores, logs, and backups where relevant.

State the search boundary in the report. Use `NOT FOUND IN CHECKED PATHS` when the inventory is incomplete; never upgrade that to “does not exist.” Do not claim “all related files were reviewed” without an explicit path set or search method.

### 4. Probe the current system directly

A historical document is evidence of what was recorded at that time, not proof of current runtime behavior. Run the smallest read-only probe that tests each important capability.

Examples:

- resolver: invoke the actual resolver with the canonical alias;
- safety gate: run a dry-run/isolated test and inspect whether the write subprocess is called;
- reminder: freeze the date/time and render the exact output;
- source: inspect current branch, commit, diff, and file presence;
- deployment: compare live destination hashes to the manifest;
- channel: separate scheduler success, script output, state mutation, and transport receipt.

Code reading creates a hypothesis. The live probe upgrades it to a finding—or falsifies it.

### 4a. Runtime reload boundary

For a long-lived gateway/daemon, the current file is not proof of the loaded implementation. Before attributing a regression to the current source:

1. Capture the live PID/start time and the hook/module-load timestamp.
2. Capture current runtime/source hash and mtime, plus the commit/change time that produced it.
3. Run a direct probe against the current file and compare it with live audit output.
4. If the process predates the fix and logs still show old behavior, classify the runtime row as `CONTRADICTED: stale loaded code`; classify the file only as `SOURCE/FILESYSTEM-PROVEN`.
5. Treat reload/restart as a separate operational gate. Do not report a file fix as live until the process has loaded it and the active path is re-tested.

### 5. Build the four-layer evidence matrix

Never collapse these layers:

| Layer | Question | Allowed status labels |
|---|---|---|
| **Original contract/design** | What was intended? What invariants were specified? | DOCUMENTED / PARTIAL / CONTRADICTED |
| **Historical candidate** | What was implemented and tested then? | HISTORICAL / TESTED-THEN / UNVERIFIED-NOW |

From amirulhazym/hermes-agent-personal_assistant, MIT.

More from amirulhazym/hermes-agent-personal_assistant