Reverse Engineering

Reverse Engineering

MANDATORY Pre-Phase 0: Branch check (multi-item exception)

RE bootstraps the entire backlog in one run, so it is the exception to the per-item branching rule. All RE artefacts land on feature/reverse-engineer-. Per-item branches kick in AFTER RE merges.

Branch check at start:

• On main / master / dev: refuse; AskUserQuestion to create

the RE branch and switch.

• On expected branch: silent continue.
• On another branch: AskUserQuestion -- switch or rename.

RE does not create per-item GitHub issues or per-item phase tags during Phase 0-7. After RE, /dia-guide runs the one-shot pass that creates issues and tags /reverse-engineered.

State in .git/dia-active-skill. Full rules: skills/project-conventions/references/team-workflow.md and branch-protection.md.

MANDATORY Phase 0: Artifact triage

Reverse engineering scans existing code to produce artifacts. Every artifact this skill creates lands in one of these categories:

• FEATURE (observed capability with user-facing surface)
• ADR (decision inferred from code patterns or external docs)
• IMP (technical debt or improvement candidate surfaced by the

scan)

• FIX (bug or drift surfaced by the scan)

The skill assigns each artifact to its category before writing. Frontmatter feature: and epic: are mandatory for FIX and IMP.

MANDATORY: Backlog as single source of truth

Every artifact this skill creates also lands as a backlog row in _devprocess/context/BACKLOG.md. Status, phase, last-change, and claim live in the row, NOT in the artifact frontmatter.

Defaults for reverse-engineered artifacts. The BACKLOG Status column uses the GitHub-aligned vocabulary (Backlog | Ready | In Progress | In Review | Done). The ADR frontmatter and the BA frontmatter carry their own status fields.

| Item | BACKLOG Status default | Frontmatter status | BACKLOG Phase | |---|---|---|---| | Feature observed in code (shipped) | Done | (none) | Released | | Feature observed in code (partial) | In Progress | (none) | Building | | ADR inferred | In Progress | Proposed (ADR / MADR) | Building | | BA draft | Backlog | Draft (Reverse-Engineered) | (n/a) |

Reverse-engineered features marked Done go straight to phase Released so the post-RE BA validation walk picks them up correctly.

Sync chain (binding order):

1. Create the backlog row
2. Create the artifact body
3. Run /consistency-check mode A at the end of the skill phase

MANDATORY: Wayfinder + rules layer as primary outputs

Wayfinder (templates under skills/architecture/templates/):

• src/ARCHITECTURE.map: one row per entry-point file.
• JSDoc headers in every entry-point file.
• Module READMEs for every src/ directory with more than 3 source

files or any cross-module API.

Rules layer at _devprocess/rules/ (hard cap 500 lines total):

• technical.md: stack (from manifests), build commands, test setup,

conventions visible in 10+ files.

• design.md (if UI surface exists): tokens, component patterns.
• domain.md: glossary from class/module names, invariants in code.

You ingest an existing codebase and produce the V-Model artifacts that should have existed from day one, so the team gets a stable, shared project context. You walk the V backwards, from Coding up through Architecture, Requirements, and Business Analysis, and fill each level only with what can be proven from the code or from existing documentation.

The result is not a product. It is a foundation: a set of artifacts every team member can trust, ready to be validated and carried forward through the normal V-Model phases.

Writing style. See skills/project-conventions/SKILL.md#canonical-specs (Writing style). Applies to every artifact this skill produces.

Three-layer model and frontmatter spec. See skills/project-conventions/SKILL.md#canonical-specs (Three-layer model boundaries, Frontmatter spec). Status, phase, last-change, and claim live in the backlog row, not in artifact frontmatter.

MANDATORY: FIX/IMP and depends-on

Work outside a Feature is either FIX-{ee}-{ff}-{nn} (bug) at _devprocess/requirements/fixes/ or IMP-{ee}-{ff}-{nn} (other) at _devprocess/requirements/improvements/. Both require frontmatter feature: and epic:. Frontmatter spec: see canonical specs link above.

Any artifact MAY carry depends-on: [ID, ID, ...] in frontmatter. The resulting graph is acyclic; targets must be existing IDs.

MANDATORY: Hypothesis statements as full prose

Epic hypothesis statements and How-Might-We headings are full prose paragraphs in the user's working language, not leftover template placeholders (FOR, WHO, THE, IS A, THAT, UNLIKE, OUR SOLUTION). The persona / problem / solution / differentiation structure stays in the substance.

Core philosophy

Backward walk, evidence only. Code tells you what exists. It does not tell you whether it solves the right problem. You do not invent personas, HMW questions, or value propositions from endpoint names or directory layouts. If a claim is not backed by a concrete source (path:line for code, doc:section for documentation), it becomes a [NEEDS USER INPUT] placeholder instead of a guess.

Draft, not ground truth. Everything this skill produces is marked as draft / observed / inferred / snapshot. The next skill (/business-analysis) validates each claim with the user and promotes the status to Validated or Accepted one section at a time.

Forward again from the validated state. After reverse engineering, the user goes through /business-analysis → /requirements-engineering → /architecture (if refactoring) → /coding. The reverse-engineered artifacts become the Phase 0 state for that forward walk.

What you create

• _devprocess/requirements/handoff/plan-context.md. Tech stack and

codebase snapshot, ready for /coding.

• _devprocess/architecture/ADR-{XXX}-{slug}.md. One per observable

architecture decision, Status: Inferred from codebase.

• _devprocess/architecture/arc42.md. Structural snapshot,

Status: Reverse-engineered snapshot.

• _devprocess/requirements/epics/EPIC-{nn}-{slug}.md. One or more

anticipated Epics grouping observed capabilities by theme (Status: Anticipated (not yet validated)). /business-analysis and /requirements-engineering later refine, split, merge, or rename.

• _devprocess/requirements/features/FEAT-{ee}-{ff}-{slug}.md. One

per observable user-facing capability (Status: Observed (not validated)), nested under its Epic.

• _devprocess/analysis/BA-{PROJECT}.md. Project-BA draft only

(singleton). Item-BAs are created by /business-analysis.

• Append entries to _devprocess/context/BACKLOG.md (TODOs,

FIXMEs, gaps, tech debt, undocumented dependencies).

What you do NOT create

• Code changes, refactorings, or new tests
• Validated Epics (Hypothesis, Outcomes, HMW). RE writes only

Anticipated Epics; strategic content comes from /business-analysis and /requirements-engineering.

• Success Criteria or User Stories beyond the observable ones

(/requirements-engineering fills the rest after BA validation).

• Personas, HMW questions, or value props that are not explicit in

existing documentation.

Anti-hallucination rules

These rules are non-negotiable. Every artifact this skill writes must comply with them, and the Quality Gates at the end check that they were followed.

1. Source per claim block. Every claim block (paragraph or table

row) carries a Source: line. Trivial restatements of an already-cited fact do not need their own Source line. The BA draft (Phase 4) is the exception: every non-placeholder sentence there still carries Source:. Format:

• For code: Source: src/api/auth/handlers.ts:42-58
• For docs: Source: README.md § "Getting Started"
• For config: Source: package.json "dependencies.prisma"

1. No source → placeholder, not a guess. If you cannot find a

concrete source for a section, you write: `` [NEEDS USER INPUT. No evidence found in {searched sources}. /business-analysis will fill this in.] `` You do not write a "reasonable assumption" in its place.

1. No persona from code structure. You never infer personas from

route names, directory names, or endpoint signatures. Endpoints are technical facts, not user research. Personas come only from explicit statements in documentation (README, marketing copy, docs/, CHANGELOG). If docs mention no user types, the persona section is a placeholder.

1. No HMW question without an explicit problem statement. If the

existing documentation nowhere states the problem the product solves, the HMW section is a placeholder.

1. Provenance marker on every file. Each file carries a

source: /reverse-engineering on {date} marker in its frontmatter (BA/ADR additionally keep their own status field; the BACKLOG row owns lifecycle status per the three-layer model).

1. One decision per ADR (with tight-coupling exception). Default

to one decision per ADR. Tightly coupled choices that share the same Context and Consequences MAY be combined into one ADR; keep them split when Context or Consequences diverge.

Workflow

You walk backwards through the V, one phase at a time. Each phase produces one or more artifacts before you move up to the next.

Phase -1: Pre-check for existing workflow artifacts (binding)

Probe the project for existing workflow residues before any scan. Greenfield projects skip this phase.

Signals to check:

• ADR or plan dirs under docs/ or _devprocess/
• README, CONTRIBUTING, CLAUDE.md references to DIA / MADR / arc42
• Multiple ADR formats or numbering series in the same directory
• DIA v1 patterns: FEATURE-NNNN (4-digit), EPIC-NNN/ADR-NNN

(3-digit), status:/phase: in YAML, > **Status**: ... lines, _devprocess/context/fixes/, _devprocess/context/20_bugs.md, numeric-prefixed 10_backlog.md, any archive/ folder

If any signal hits, stop and ask the user via AskUserQuestion:

> "Existing workflow artifacts under {paths}. Proceed how? > (a) normalize to current DIA conventions first (Phase -1.5 runs > the migration scripts), then reverse-engineer gaps; (b) keep > untouched, produce new artifacts alongside (flagged as separate > source); (c) replace with reverse-engineered versions (destructive)."

Recommend (a) for DIA v1 patterns, (b) for non-DIA workflows worth preserving, (c) only when the user confirms existing artefacts are obsolete.

Phase -1.5: Migration of pre-existing artefacts

Runs only if Phase -1 chose option (a). Shares the canonical migration mechanics with /dia-migration (which confirms phase by phase; RE runs them as one consolidated pass).

Sequence (each script idempotent):

1. tools/migration/detect_state.py -- inventory v1/v2/mixed signals.
2. strip_frontmatter_status.py -- pull status: / phase: /

last_updated: out of YAML.

1. strip_body_status.py -- pull > **Status**: ... lines.
2. migrate_naming.py -- rename ID schemas, rewrite cross-refs.
3. flatten_analysis.py -- collapse analysis/ to the four

canonical prefixes (BA, EXPLORE, RESEARCH, AUDIT).

1. build_backlog.py -- regenerate BACKLOG.md.
2. migrate_skill_names.py -- rewrite legacy skill names in

CLAUDE.md / README / inline scripts.

Numbering collisions. If two ADR series coexist, the series with the higher count of external references in code/commits/backlog wins; renumber the smaller series with a note in the renumbered ADR header.

Dedup. Two files describing the same topic: merge under the newer structure and add a "Previous variants" note. No silent deletes.

Phase 0: Scope and codebase scan (5-10 min)

Ask the user which scope applies, same tiers as /business-analysis:

What is the scope of this reverse-engineering run?

A) Simple Test / single-feature onboarding
 -> Scan the affected module, produce minimal artifacts
 -> Timeframe: 30-60 min

B) Proof of Concept / small repo
 -> Full tech-stack extraction, 3-8 ADRs, 5-15 features, BA draft
 -> Timeframe: 1-3 h

C) Minimum Viable Product / full project onboarding
 -> Full arc42 snapshot, 8+ ADRs, 15+ features, full BA draft,
 complete backlog seed
 -> Timeframe: 3-8 h

Then scan the codebase structure and list:

• Package / build manifests (package.json, pyproject.toml,

Cargo.toml, go.mod, pom.xml, Gemfile)

• Top-level directories and their apparent purpose
• Entry points (main.*, app.*, index.*, src/index.*)
• Test directories and test runner config
• CI config (.github/workflows/*, .gitlab-ci.yml, etc.)
• Lint/format config, tsconfig/pyproject, etc.
• Existing documentation (README.md, docs/, CHANGELOG.md,

CONTRIBUTING.md, ARCHITECTURE.md)

Report this as a Codebase Map before proceeding. This is the inventory you will draw sources from for the rest of the walk.

Phase 1: Tech stack → plan-context.md

Extract the concrete tech stack from the manifests and entry points. One Sources: line per Tech Stack block is sufficient (not per row):

## Tech Stack

- **Runtime:** Node.js >=20
- **Language:** TypeScript 5.4
- **Framework:** Next.js 14 App Router
- **Database:** PostgreSQL via Prisma
- **Auth:** NextAuth 5.x
- **Testing:** Vitest + Playwright

Sources: package.json, tsconfig.json, prisma/schema.prisma, vitest.config.ts, e2e/

Write the result into _devprocess/requirements/handoff/plan-context.md using the same structure the /architecture skill produces, with the header:

---
status: Snapshot from existing code
source: /reverse-engineering on {date}
---

The Codebase Layout, Conventions, and Existing Patterns sections of plan-context.md are filled from the scan in Phase 0.

Phase 2: Architecture reverse engineering → ADRs + arc42

Walk through the codebase and identify decisions that are visible and consequential. For each, write one ADR in MADR format with:

• Status: Inferred from codebase in the frontmatter
• Context: what you see in the code that implies this decision was

made (with source)

• Decision: the observable choice
• Alternatives considered: leave as `[NEEDS USER INPUT, not visible

in code]` unless the alternatives are mentioned in a comment or doc

• Consequences: only the ones you can see (e.g. lock-in, operational

implications that are visible in CI config)

• Source: footer with all files/lines that support the decision

When to write an ADR. Only when the decision is consequential AND non-obvious from framework defaults. Skip the rest.

Write ADRs to _devprocess/architecture/ADR-{XXX}-{slug}.md, numbered in the order you discovered them.

Then produce _devprocess/architecture/arc42.md as a snapshot. Fill only the sections you can back with sources:

• §1 Introduction and Goals: copy from README/docs if present,

otherwise placeholder

• §2 Architecture Constraints: from package.json engines, CI

targets, license file

• §3 System Scope and Context: from entry points + external

integrations you can see in config

• §4 Solution Strategy: reference the inferred ADRs
• §5 Building Block View: from top-level directories + module

boundaries you can observe

• §6 Runtime View: placeholder unless explicit docs exist
• §7 Deployment View: from CI config and Dockerfile/k8s manifests

if present

• §8 Crosscutting: from config (auth, logging, error handling)
• §9-12: placeholders unless evidence exists

Header of arc42:

---
status: Reverse-engineered snapshot
source: /reverse-engineering on {date}
---

Phase 3: Functional reverse engineering → Anticipated Epics + FEATURE inventory

Identify observable user-facing capabilities. A feature is anything the system lets a user (or an API consumer) do. Sources:

• Routes / controllers / CLI commands / public API endpoints
• Rendered pages / navigation entries
• Public exports if th

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pssah4
• Source: pssah4/digital-innovation-agents
• License: MIT
• Homepage: https://pssah4.github.io/digital-innovation-agents/

Install and usage instructions live in the source repository linked above.