Skip to content
Skills Library
Programming · Analysis

reverse-spec

/reverse-spec

Use to extract a spec FROM existing code. Inverse of "build from spec" — given the code, recover what it does. Useful for: legacy systems, undocumented modules, post-hoc compliance evidence.

Repository
sift-coder ↗
Licence
MIT
Last repository change
03.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use to extract a spec FROM existing code. Inverse of "build from spec" — given the code, recover what it does. Useful for: legacy systems, undocumented modules, post-hoc compliance evidence.

Triggers from the description

build from spec
Original author description

Use to extract a spec FROM existing code. Inverse of "build from spec" — given the code, recover what it does. Useful for: legacy systems, undocumented modules, post-hoc compliance evidence.

How it works

  1. Method
  2. Output shape
  3. Rules
  4. Anti-patterns
  5. When NOT to use
  6. Subagent dispatch
  7. Value over native CC
Original SKILL.md headings · 85 lines, 448 words
SKILL.md preview
---
name: reverse-spec
description: Use to extract a spec FROM existing code. Inverse of "build from spec" — given the code, recover what it does. Useful for: legacy systems, undocumented modules, post-hoc compliance evidence.
---

# reverse-spec

Code → spec. Reads a module/service/feature and writes the spec it implements.

## Method

1. **Anchor.** Pick the surface: a directory, a class, an HTTP service, a CLI command.
2. **Walk the public surface.** Every entry point gets:
   - What it accepts (params, headers, env)
   - What it does (one sentence)
   - What it returns (success + error shapes)
   - Side effects (writes, calls, mutates)
3. **Behaviour from tests.** If the area has tests, each test name is a one-line behaviour assertion. Aggregate.
4. **Behaviour from code paths.** For each non-trivial branch, name the trigger and outcome.
5. **Unstated assumptions** (mine via `/invariant` skill if helpful).
6. **Synthesise spec** in the same shape `improve-spec` would produce — overview, actors, behaviour, AC, edge cases, non-goals.
7. **Confidence per claim.** Test-backed claims = high; code-only claims = medium; inferred-from-comments = low.

## Output shape

```
Source:     <directory / module / service>
Coverage:   N entry points walked

# Spec: <inferred title>

## Overview
<one-paragraph capability description>

## Actors
<inferred from auth checks, headers, role guards>

## Behaviour
- B1 [high]    <test-backed behaviour>
- B2 [med]     <code-only behaviour>
- B3 [low]     <inferred from comment>

## Acceptance Criteria (test-backed)
- AC1 → tests/foo.test.ts:42 — <one-liner>
- AC2 → tests/foo.test.ts:78 — <one-liner>

## Edge Cases (from code branches)
- Empty input → returns []
- Auth missing → 401
- DB error → propagated; no retry

## Non-goals (inferred from absence)
- Pagination (no cursor/limit handling found)
- Caching (no cache layer detected)

## Open questions
- Q1: <ambiguity in code; behaviour unclear>
```

## Rules

- **Confidence labels mandatory.** Don't pretend code-only inference is the same as test-backed.
- **Cite test files for AC.** Each test name → AC line.
- **Surface ambiguities.** When code does X but it's unclear if X is intended, flag it.
- **Don't fabricate non-goals.** Inferred non-goals are explicit absences; speculation is open question.

## Anti-patterns

- Treating implementation detail as AC (e.g. "uses Redis" — internal, not spec)
- Skipping confidence labels
- Long prose summaries instead of structured spec
- Inferring requirements that the code happens to satisfy but didn't intentionally

## When NOT to use

- Code with up-to-date spec — read the spec instead
- Active development — moving target
- Generated code — spec is in the source-of-truth schema, not the gen output

## Subagent dispatch

- `Explore` for the walk
- `archaeologist` if the spec needs git/memory context for "why"
- `general-purpose` for the synthesis

## Value over native CC

CC will summarise code. CC won't naturally produce spec-shaped output with confidence labels and AC backlinks. The structure IS the value — the output is auditable and feeds compliance evidence.

Versions

RepositoryScoreLicence
This page · ialameh/sift-coder100MIT
tammai/rspec90MIT

Database snapshot: 13.11.2026 · package version 16110f60edf2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-to-spec
    Reverse-engineer a SPEC document from an existing project. Analyzes code, config, tests, and structure to produce a comprehensive specification. Triggers on: code-to-spec, reverse spec, generate spec, 逆向规格, 生成规格文档, 生成设计文档, 生成设计方案, extract spec, document this project, what does this project do.
  • 100spec-miner
    Reverse-engineering specialist that extracts specifications from existing codebases. Use when working with legacy or undocumented systems, inherited projects, or old codebases with no documentation. Invoke to map code dependencies, generate API documentation from source,…
  • 95reverse
    [UDS] System archeology — reverse engineer an existing system across the Logic, Data, and Runtime dimensions. Use when: documenting an undocumented system, recovering specifications from existing code, mapping an unknown data model or runtime topology. Not for: assessing health…
  • 100spec-miner
    Reverse-engineering specialist that extracts specifications from existing codebases. Use when working with legacy or undocumented systems, inherited projects, or old codebases with no documentation. Invoke to map code dependencies, generate API documentation from source,…
  • 100legacy-spec
    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…
  • 9000-spec
    Author or update authoritative technical specifications under docs/spec/ (global.md for system-wide architecture/invariants and <unit>.md for subcommands or modules) before writing implementation code. Activate when planning architecture, reverse-engineering legacy code, or running /00-spec.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.