deconstruct

Files (5)

• SKILL.md
• decon-epic-template.md · references/
• manifest-template.md · references/
• methodology.md · references/
• vectors-readme-template.md · references/

SKILL.md (first lines)

# Deconstruct

Turn a working codebase into a **regeneration pack**: a self-contained folder
of language-agnostic epics plus machine-extracted golden vectors, sufficient
for a person or agent to rebuild the functionality in any language, free of
the original's design choices.

`/epic` goes design → code. `/deconstruct` is its inverse: code → design.
Citations into the source prove a behavior is real; they never bind the
rebuilder.

## Usage

- `/deconstruct` — deconstruct the whole repo.
- `/deconstruct <subsystem>` — scoped run: produce or update only the epics
  covering `<subsystem>`, then re-derive the manifest coverage table.

**Update mode:** if a pack already exists (a `deconstruct/MANIFEST.md` under
the repo's docs folder), never clobber it. Refresh vectors at the current
commit, reconcile epic text against current behavior, and record drift in the
manifest's Drift log. Never renumber existing DECON epics.

## The pack

Write into `<docs-dir>/deconstruct/` (detect the repo's docs folder the same
way /epic does — prefer wherever design markdown already lives; default
`docs/`):

    docs/deconstruct/
      MANIFEST.md                       ← index & entry point
      DECON-01_Name.md …                ← epics, own numbering, build order
      APPENDIX_Engineering_Constraints.md
      vectors/
        README.md                       ← vector format contract
        <epic-slug>/*.json              ← golden vectors per epic

The pack must be portable: copy the folder out and hand it to any agent —
nothing in it may depend on access to the source repo.

## What you must do when invoked

**Before writing anything**, read `references/methodology.md` in this skill
dir, and `~/.claude/skills/epic/references/methodology.md` — the /epic voice
and kata framing carry over; this skill's methodology defines the deltas
(the "deconstruct profile").

### Phase 1 — Survey

Fan out subagents over four signals; keep the conclusions, not the file
dumps:

1. **Public surface** — every observable capability: the domain's things,
   operations, orderings, formats, locales.
2. **Test mining** — what the tests promise; note coverage gaps. Where
   coverage is weak, vectors still come from the dumper in Phase 3 (it
   exercises the public API directly, independent of the test suite), but
   the weak grounding means any spec-decision flag on that behavior gets
   extra scrutiny before it's resolved.
3. **Docs mining** — README, CHANGELOG, design docs: what was intended.
4. **Perspective analysis** — which actor perspectives the code supports
   (god-mode / administrative / user-client / observer-operator, plus any
   repo-specific ones), each rated Full / Partial / Absent with evidence,
   behind what boundary invariants. For observer: which domain events are
   visible without side effects. Also rate the two quality lenses:
   **performant** (how performant is it — complexity, allocation behavior,
   benchmarks) and **flexibility** (where and how can it run — environments,
   optional-capability layering), as characteristics in observable terms.

Merge into a **behavior inventory**: each entry tagged `domain-essential` or
`implementation-accident` (litmus test in the methodology), plus a draft
**perspectives taxonomy** from signal 4's ratings. Where the signals
disagree — or an observable output hangs off an accidental choice — record a
**spec decision** flag; never silently resolve.

### Phase 2 — Map (the one checkpoint)

Cluster the inventory into epics with a dependency order. Draft `MANIFEST.md`
from `references/manifest-template.md`. Then pause ONCE: present the epic
list, per-epic scope, out-of-scope rows, and the perspectives taxonomy via
AskUserQuestion. The user's approval (with edits) is the gate. No other
checkpoints — after this, generate everything.

### Phase 3 — Generate

For each epic, in dependency order:

1. Write `DECON-NN_Name.md` from `references/decon-epic-template.md`,
   following the deconstruct profile.
2. Extract golden vectors by **running the original code**: write a dumper
   program in the source language, using only the public API, that
   serializes the epic's observable behaviors to JSON under
   `vectors/<epic-slug>/`. The dumper is committed to the source repo (e.g. a
   Rust example) so vectors stay regenerable. **Never hand-write vector
   values.** If you cannot run the code, say so and stop — do not fabricate.
3. Maintain `vectors/README.md` from `references/vectors-readme-template.md`
   (create with the first epic; extend its file table with each subsequent
   one).

Also write `APPENDIX_Engineering_Constraints.md`: platform and engineering
traits (e.g. no_std, wasm targets, MSRV, performance posture, CI matrix) as
context for rebuilders, explicitly marked non-normative.

### Phase 4 — Audit

1. **Coverage** — walk the public surface again; every observable behavior
   must map to an epic or an explicit out-of-scope row in the manifest.
2. **Anti-constraint lint** — search epic bodies for source-language type
   names, crate names, and idioms outside `## Provenance` sections; rewrite
   neutrally or move into Provenance.
3. **Perspective consistency** — every epic's `## Perspectives` section uses
   only perspectives defined in the manifest taxonomy (or N/A); every
   non-Absent **actor** perspective in the taxonomy is addressed by at least
   one epic. Quality lenses (performant, flexibility) are satisfied by their
   manifest ratings plus the engineering appendix; epics mention them only
   where a slice has a notable characteristic, and any lens finding stated
   as binding must carry an SD flag.

Fix findings, then report the audit results in your final summary.

From folkengine/.claude, Apache-2.0.

More from folkengine/.claude