artifact-resurfacing

Files (8)

• SKILL.md
• 2026-05-17-praxis-perpetua-resurfacing.md · examples/
• buried-bodies-taxonomy.md · references/
• composition-with-closeout.md · references/
• constitutional-doc-policy.md · references/
• audit-citations.sh · scripts/
• find-orphan-plans.sh · scripts/
• propose-citation-fix.py · scripts/

SKILL.md (first lines)

# Artifact Resurfacing

Open the drift on the table. Surface the buried artifacts — stale citations, missing referenced files, orphan plans, cross-scope memory entries pointing at paths that moved. Polish them in proposal form. Codify the lesson so the next session does not have to re-discover the same drift.

## Authority boundary (read first)

This skill is **propose-not-apply** for any constitutional surface. It produces drift tables, edit diffs, and IRF row proposals. It does not commit edits to `CLAUDE.md`, `MEMORY.md`, `governance-rules.json`, `registry-v2.json`, or any `seed.yaml` without explicit conductor authorization in the same session.

- **Closure for plans** — defer to [`closeout`](../closeout/SKILL.md). This skill does not assign DONE-NNN / IRF-XXX-NNN labels; it surfaces orphans for closeout's classifier.
- **Memory operations** — defer to your agent's memory-curation tool (for example, a built-in memory-consolidation skill, where the platform provides one) for memory file mutations. This skill emits proposed memory diffs.
- **Cross-session continuity** — defer to [`cross-agent-handoff`](../cross-agent-handoff/SKILL.md). This skill writes the polish-log entry; handoff carries it forward.
- **Verification of claimed transitions** — defer to [`qa-audit`](../qa-audit/SKILL.md).

Discovery ≠ remediation. The skill *finds* and *proposes*. The conductor *applies*.

## When to use

- "Resurface buried artifacts in <domain>"
- "Find stale citations in this CLAUDE.md"
- "Reconcile memory drift between scopes"
- "Audit this domain for orphans"
- "Polish referenced-but-missing files"
- "Future-fix this so it doesn't drift again"
- Closeout has surfaced ≥3 follow-ups whose root cause is drift between memory and disk
- A `MEMORY.md` walkback flags ≥1 stale path citation
- A `find` for a CLAUDE.md-cited path returns zero results

## Four-phase protocol

### Phase 1 — Detect

Enumerate the domain's surface. For a target `CLAUDE.md` or `MEMORY.md`, extract every:

- File path (absolute or `~/`-anchored)
- Function/script identifier (`foo.py`, `bar()`, `--flag`)
- Issue/ledger ID (`IRF-XXX-NNN`, `DONE-NNN`, `GH#123`)
- External reference (URL, package name, doc anchor)
- Plan filename (any `~/.claude/plans/*.md` referenced by path)

Run the citation audit:

```bash
bash scripts/audit-citations.sh <path-to-CLAUDE.md>
```

The script emits one JSONL record per citation: `{cited, kind, exists, found_at, status}`. A path is **present** if `test -f` (or `test -d`) succeeds. It is **stale** if a different path on disk holds the same canonical content (e.g., the institution moved from `~/Workspace/...` to `~/Code/...`). It is **missing** if no candidate path holds the artifact.

Run the orphan-plan scan:

```bash
bash scripts/find-orphan-plans.sh [glob]
```

Default glob is `~/.claude/plans/*.md`. Output: one JSONL record per plan, with `{path, mtime, has_done_ref, has_irf_ref, has_delivered_research_marker}`. Plans lacking all three markers are orphan candidates.

Surface a four-column finding table to the user before classifying:

| artifact | cited-at | status | candidate-action |
|---|---|---|---|
| ... | ... | present \| stale \| missing \| orphan | (proposed action, no execution yet) |

### Phase 2 — Classify

For each finding, assign one class:

- **Present** — no action.
- **Stale-citation** — the artifact exists on disk; the citation points at the wrong path. Polishable via citation rewrite.
- **Missing-but-probably-never-written** — citation appears to run ahead of an unwritten artifact (e.g., a paper title cited with no draft, no commit history, no cross-scope mention). Polishable via citation annotation (`(planned — not yet written, YYYY-MM-DD)`) rather than reconstruction.
- **Missing-but-lost** — citation points at an artifact whose creation history exists somewhere (a session transcript, an old commit, a cross-scope memory file) but the artifact itself is gone. Polishable via deep search; if search fails, propose reconstruction-from-context or citation removal.
- **Orphan-plan** — pass through to [`closeout`](../closeout/SKILL.md)'s classifier (EXECUTED / IN-PROGRESS / ABANDONED / DELIVERED-RESEARCH). This skill does not assign closure labels.

For ambiguous classifications, surface the finding to the conductor and stop. Universal Rule #21 ("Do what is asked — never preempt") applies.

See `references/buried-bodies-taxonomy.md` for the full taxonomy with worked examples.

### Phase 3 — Polish (propose, do not apply)

For each classified finding, generate a polish artifact. **Never write directly to constitutional files.** Emit diffs and proposals instead.

For **stale citations**, run the proposer:

```bash
python3 scripts/propose-citation-fix.py \
  --file <path-to-CLAUDE.md-or-memory-file> \
  --stale-path <wrong-path> \
  --canonical-path <correct-path>
```

Output: a unified diff to stdout. The conductor reviews and applies (or rejects) the diff via Edit. The script never writes the file itself.

For **missing-probably-never-written**, emit a one-line annotation diff:

```diff
- See ~/path/to/cited-but-missing.md for details.
+ See ~/path/to/cited-but-missing.md for details (planned — not yet written as of YYYY-MM-DD).
```

For **missing-but-lost**, emit the deep-search command set first:

```bash
find /Users/4jp -name "<artifact-name>*" 2>/dev/null | grep -v node_modules
grep -rl "<artifact-keyword>" ~/.claude/projects/*/memory/*.md 2>/dev/null
grep -rl "<artifact-keyword>" ~/Code/organvm/praxis-perpetua/prompt-corpus/ 2>/dev/null
```

If the search returns hits, the finding reclassifies as stale-citation and the citation-fix proposer runs. If the search returns zero hits across the deep corpus, the finding reclassifies as probably-never-written and the annotation diff applies.

For **orphan plans**, hand the plan path to `closeout` with a classification request. Do not move plans to `abandoned/` from this skill — closeout owns that decision.

See `references/constitutional-doc-policy.md` for the full rule set on what may/may not be auto-edited.

### Phase 4 — Codify (future-fix)

Polishing one drift instance is tactical. Codifying so the *next* drift self-corrects is strategic.

For each polished finding, append an entry to a `polish-log.md` in the affected repo's root (create if absent):

```markdown
## YYYY-MM-DD — <one-line summary>

From 4444J99/a-i--skills, MIT.

More from 4444J99/a-i--skills