Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

legacy-spec

/legacy-spec

Odtwarza specyfikację nieudokumentowanego systemu legacy moduł po module, zapisując ustalenia z odwołaniami do plików i linii.

Repozytorium
claude-plugins ↗
Licencja
MIT
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Odtwarza specyfikację nieudokumentowanego systemu legacy moduł po module, zapisując ustalenia z odwołaniami do plików i linii.

Oryginalny opis (EN)

Reverse-engineer an undocumented legacy system into a validatable specification. Works unit by unit so large systems fit the context window, writes every finding to disk under spec/ with file:line citations, and resumes from the on-disk state in any session. Use when asked to document, spec, reverse-engineer, or understand a legacy codebase or database before a rewrite, migration or handover.

Jak działa

  1. Why unit by unit
  2. On-disk layout (created by init, inside the user's project)
  3. Procedure: init
  4. Procedure: next / run
  5. Procedure: data
  6. Procedure: assemble
  7. Rules
Sekcje z nagłówków SKILL.md, w oryginale · 112 linii, 985 słów
Podgląd SKILL.md
---
name: legacy-spec
description: Reverse-engineer an undocumented legacy system into a validatable specification. Works unit by unit so large systems fit the context window, writes every finding to disk under spec/ with file:line citations, and resumes from the on-disk state in any session. Use when asked to document, spec, reverse-engineer, or understand a legacy codebase or database before a rewrite, migration or handover.
---

# legacy-spec

Goal: a `spec/` folder a domain expert can validate and a new team can build from. Not a code
summary. Every behavioural claim cites where it came from (`path:line` or `table.column`).
Anything the code does not prove goes to **Open questions**, never to prose as fact.

## Why unit by unit

A legacy system rarely fits in one context window and never fits in one sitting. The plugin
therefore keeps all state on disk and treats each unit as one loop iteration:

```
read state → pick next pending unit → read its files → write modules/<unit>.md
→ append glossary/data/questions → mark done → (repeat or stop)
```

A unit is a directory (or a single oversize file) whose text totals at most `--max-lines`
(default 4000). Stopping after any unit loses nothing. A fresh session picks up from
`spec/_state/progress.tsv`.

## On-disk layout (created by `init`, inside the user's project)

```
spec/
  _state/
    inventory.tsv     path  ext  lines  bytes  mtime  kind       (from inventory.sh)
    progress.tsv      unit  status  files  lines  path  notes    (pending|in-progress|done|skipped)
    plan.md           inputs available, chosen max-lines, user decisions, conventions found
  overview.md         what the system is for, who uses it, how it runs (filled as units reveal it)
  index.md            tree map: every unit → purpose, one line, link   (assemble)
  glossary.md         domain terms found in code: name | meaning | evidence
  open-questions.md   numbered, each tagged with unit and what would answer it
  data-model/
    tables.md         one section per table: columns, keys, who reads/writes it (unit refs)
    erd.md            mermaid erDiagram inferred from FKs, joins and naming
  modules/
    <unit-id>.md      one per unit (template below)
  interfaces/
    <name>.md         anything crossing the boundary: files, screens, jobs, APIs, queues, reports
```

## Procedure: init

1. Ask (or take from `$ARGUMENTS`) the source directory. Ask what else exists, in this order of value:
   a database schema dump, runtime samples (log files, exported reports, screenshots as text),
   and anyone who can answer questions. Record answers in `_state/plan.md`.
2. Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/inventory.sh --src <dir> --out spec/_state/inventory.tsv`.
   Summarise: files, lines, extensions, binary and data files that will be listed but not read.
3. Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/plan.sh --inventory spec/_state/inventory.tsv --max-lines <N>`.
   Show the proposed units (id, path, files, lines). Flag `oversize`. Ask the user to confirm,
   merge, split or skip units (generated code, vendored libraries and tests are usual skips).
   Default max-lines 4000. Raise it only if the user wants fewer, larger units.
4. Write `spec/_state/progress.tsv` with the header
   `unit\tstatus\tfiles\tlines\tpath\tnotes` and every confirmed unit as `pending`.
5. Create the skeleton: every file in the layout above, with headings and an empty body.
   `overview.md` gets whatever the user already told you, marked as *stated by user*.
6. Run `grep` hints to seed `interfaces/`: look for screen/form/menu definitions, scheduled jobs,
   SQL strings, file open/read/write, network calls, printing/report calls. Write one line per
   hit group into `_state/plan.md` under **Entry point hints**. Do not spec anything yet.
7. Tell the user how many units are pending and that `/legacy-spec next` or `run` continues.

## Procedure: next / run

For each unit, in order of `progress.tsv`:

1. Set status `in-progress`. Read every text file of the unit (from `inventory.tsv`). For an
   `oversize` unit read in sections of ~1500 lines and keep notes between sections.
2. Write `spec/modules/<unit-id>.md` using `templates/module.md`. Rules:
   - Name things the way the code does, then the business term if one is evident. Add both to
     `glossary.md`.
   - Every rule, validation, calculation, branch that depends on data, status transition, and
     hard-coded constant gets a bullet with a `path:line` citation.
   - For every table, file, queue or external call touched: add or update its row in
     `data-model/tables.md` or `interfaces/<name>.md` with this unit as reader/writer.
   - Dead or unreachable code: list it under **Suspected dead code**, do not spec it as behaviour.
   - Anything inferred rather than read (why a rule exists, what a magic number means, who uses
     a screen) goes to `open-questions.md` with the unit id and the file:line that raised it.
3. Set status `done` with a one-line note (purpose). If the unit turned out to be generated code,
   vendored library or pure test, set `skipped` and say why.
4. After each unit, print one line: `done <unit> (<n> rules, <m> tables, <q> questions). Next: <unit>`.
5. `run`: continue while units are pending. If the context has grown large (you have read more
   than roughly 60k lines of source in this session), stop after the current unit and say so.
   The next session resumes.

## Procedure: data

Input is a schema dump as text (DDL, information_schema export, ORM models, or a stored-procedure
dump). No database connection is used. For each table write a section in `data-model/tables.md`:
columns with type and nullability, primary key, foreign keys (explicit, or inferred from naming
and noted as inferred), indexes, triggers and constraints. Then write `data-model/erd.md` as a
mermaid `erDiagram`. Mark inferred relations with a dashed comment. Stored procedures and triggers
are spec'd like code units: rules with citations into the dump file.

## Procedure: assemble

1. Read every `modules/*.md` title and purpose line; write `index.md` as a tree following the
   source directory structure, one line per unit, with links. Mark `skipped` units as such.
2. Rewrite `overview.md`: purpose, actors, main flows (as a short list that references modules),
   runtime shape (how it starts, what schedules it, what it talks to), from the module specs only.
3. De-duplicate `glossary.md` (same term, merge evidence). Sort.
4. Renumber `open-questions.md`, group by unit, mark any that another unit later answered.
5. Report counts: units, rules cited, tables, interfaces, open questions.

## Rules

- Never state behaviour without a citation. Never paraphrase a rule more loosely than the code.
- Do not modernise, judge or propose a target architecture. That is a separate task.
- Do not read binary or `data` kind files; list them in the module's **Inputs/outputs** as present.
- Keep the user's domain language; do not translate identifiers.
- One unit per iteration, state written before moving on. Never hold more than one unit in flight.
Pliki w paczce (3)
  • SKILL.md 7 KB
  • templates/module.md 1 KB
  • templates/plan.md 1 KB

Wersje

W bazie nie ma innych skilli o nazwie legacy-spec.

Migawka bazy z 13.11.2026 · wersja paczki cf008adab86f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100reverse-spec
    Odzyskuje specyfikację z istniejącego kodu: co on robi dla starych systemów, modułów bez dokumentacji i dowodów zgodności po fakcie.
  • 84reverse-engineer
    Odtwarza dokumentację istniejącego systemu bez opisu: logikę, model danych i topologię, na podstawie kodu.
  • 100code-to-spec
    Odtwarza dokument specyfikacji z istniejącego projektu, analizując kod, konfigurację, testy i strukturę.
  • 100spec-miner
    Odtwarza specyfikacje z istniejących baz kodu: mapuje zależności, generuje dokumentację API ze źródeł, wyłapuje nieudokumentowaną logikę biznesową i architekturę w starych systemach.
  • 100spec-miner
    Wyciąga specyfikacje ze starych baz kodu, mapuje zależności i logikę biznesową oraz dokumentuje architekturę z implementacji.
  • 95reverse
    Odtwarza specyfikację istniejącego systemu z kodu i runtime: model danych, logikę i topologię, gdy brakuje dokumentacji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.