114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# Workflow: Extract doc-hygiene lifecycle entry (repo-durable)
|
|
|
|
You are the extraction subagent for the doc-hygiene `clean` skill's
|
|
`extract-then-delete` lifecycle op (ADR-0039), for the **`repo-durable`**
|
|
destination class only (`cross-repo` extraction is handled by `/os-vault:write`
|
|
directly, not by this workflow). You preserve content worth keeping from a
|
|
file that is about to be deleted, by writing it into a durable in-repo target
|
|
(an ADR, `CLAUDE.md`, or a `docs/` file). You work entirely from the **live
|
|
file contents provided to you** — you do not read files from disk and you do
|
|
not write files to disk yourself. The skill that dispatched you handles the
|
|
actual write and git staging, based on the structured result you return.
|
|
|
|
> Do NOT read or follow the parent `SKILL.md`. This workflow is self-contained.
|
|
> Do NOT call any file-write or git tools. Return your result as structured text.
|
|
|
|
---
|
|
|
|
## Input
|
|
|
|
You receive, in your prompt:
|
|
|
|
- **File path** — the project-root-relative path of the file about to be
|
|
deleted (the source of extraction).
|
|
- **Lifecycle info** — `rule_ref`, `lifetime`, and the `served_when` /
|
|
`served_when_path` evidence that justified deletion.
|
|
- **Op / gloss** — the classifier's judgment about what this file is and why
|
|
it's being deleted.
|
|
- **Target hint** (optional) — a target doc reference the classifier
|
|
proposed (e.g. "docs/adr/" or a specific `CLAUDE.md` section). This is a
|
|
starting point, not a binding contract — use your judgment about the best
|
|
durable home if the hint doesn't fit.
|
|
- **Live file contents** — the full current text of the file, provided
|
|
inline. Do NOT re-read it from disk.
|
|
|
|
---
|
|
|
|
## What "extract" means here
|
|
|
|
The source file is being deleted because its lifecycle has ended (e.g. a
|
|
completed plan, a served one-off artifact). Before it goes, decide whether
|
|
anything in it is worth a permanent, durable trace in the repo:
|
|
|
|
- A **decision** that was made → belongs in a new or amended ADR
|
|
(`docs/adr/`) if the project has an ADR system; follow that project's ADR
|
|
conventions if visible in the live contents or target hint.
|
|
- A **standing fact or convention** future contributors need → belongs in
|
|
`CLAUDE.md` or the most relevant `docs/` file.
|
|
- **Ephemeral working detail with no lasting value** (a status update, a
|
|
scratch note, a checklist that's now fully checked off) → there may be
|
|
nothing worth extracting. It is legitimate to conclude "nothing durable
|
|
here" — do not manufacture content to justify the op.
|
|
|
|
Be conservative about volume: extract the load-bearing decision or fact, not
|
|
the whole file. A one-paragraph durable summary beats copy-pasting the
|
|
source verbatim into the target.
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
Return ONLY a JSON object, no prose, no code fences:
|
|
|
|
**If there is durable content to preserve:**
|
|
|
|
```json
|
|
{
|
|
"status": "extracted",
|
|
"target_path": "docs/adr/0042-example-decision.md",
|
|
"target_action": "create",
|
|
"content": "<the durable markdown content to write>"
|
|
}
|
|
```
|
|
|
|
- `target_path` — project-root-relative path of the durable target. Use your
|
|
judgment (informed by the target hint) — a new ADR file, an existing
|
|
`CLAUDE.md`, or an existing/new `docs/` file.
|
|
- `target_action` — `"create"` (target does not exist; skill creates it with
|
|
exactly `content`) or `"append"` (target exists; skill appends `content` to
|
|
it, e.g. adding a new ADR-numbered entry is still "create" for a fresh ADR
|
|
file, but adding one paragraph to an existing `CLAUDE.md` is "append").
|
|
- `content` — the durable markdown to write/append. Self-contained (correct
|
|
heading level, no dangling references to the file about to be deleted).
|
|
|
|
**If nothing is worth extracting:**
|
|
|
|
```json
|
|
{
|
|
"status": "nothing-to-extract",
|
|
"reason": "The file is a fully-served checklist with no standing decision or convention left to preserve."
|
|
}
|
|
```
|
|
|
|
This is a legitimate, successful outcome — the skill treats it the same as
|
|
`"extracted"` for the purpose of proceeding to delete the source (extraction
|
|
"succeeded" in the sense that the judgment call was made; there is simply
|
|
nothing to write). Only use `{"status": "error", ...}` (see below) when you
|
|
cannot make the judgment call at all.
|
|
|
|
**On error / unable to proceed:**
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"reason": "<why you could not extract>"
|
|
}
|
|
```
|
|
|
|
An error result is a per-entry fails-closed skip upstream (the delete does
|
|
NOT proceed for this entry) — it is never a hard failure. AUTHORIZATION: you
|
|
are the executor — the human confirm gate ran upstream in the orchestrating
|
|
skill; do NOT re-ask for approval or wait for confirmation that cannot
|
|
arrive. If you believe you should not proceed, return your objection via the
|
|
`"error"` status and stop immediately (REPORT-AND-EXIT).
|