codebase-spec-extractor

Codebase Spec Extractor

Overview

Extract engineering specifications from existing codebases with one goal: produce documentation so complete that the project can be fully replicated without seeing the original source code.

This is NOT about filling templates. This is about deconstructing every detail and documenting it with engineering precision.

Requirements

• bash (macOS default Bash 3.2 supported)
• Standard Unix tools: find, grep, sed, wc, date
• Optional (recommended): rg (ripgrep) for faster scans in large repos

When to Use

• You need implementation-grade specs for a codebase (migration, rewrite, onboarding, vendor handoff).
• You keep finding “implicit rules” in code and want them made explicit.
• You want a repeatable inventory + spec skeleton + verification workflow.

When NOT to Use

• You only need a quick architecture overview or a lightweight README update.
• Your main goal is security auditing, performance profiling, or code style cleanup (use dedicated workflows/tools).
• The repository contains highly sensitive data and you cannot safely store path-rich reports/specs.

Core Principle: Deconstruction Thinking

The framework is a guide, not a boundary. Real projects are messy, creative, and often surprising. Your job is to:

1. Discover what exists (not assume what should exist)
2. Understand why it exists (not just what it does)
3. Document how to replicate it (not just describe it)

The Deconstruction Questions

For EVERY piece of code, structure, or behavior you encounter, ask:

┌─────────────────────────────────────────────────────────────────┐
│                 The 7 Deconstruction Questions                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. WHAT is this?                                               │
│     → Name it. Classify it. Place it in context.                │
│                                                                 │
│  2. WHY does it exist?                                          │
│     → What problem does it solve? What would break without it?  │
│                                                                 │
│  3. HOW does it work?                                           │
│     → Step-by-step logic. Every branch. Every edge case.        │
│                                                                 │
│  4. WHAT are its inputs?                                        │
│     → All forms. All sources. All validations.                  │
│                                                                 │
│  5. WHAT are its outputs?                                       │
│     → All forms. All destinations. All side effects.            │
│                                                                 │
│  6. WHAT depends on it? What does it depend on?                 │
│     → Upstream. Downstream. External.                           │
│                                                                 │
│  7. WHAT can go wrong?                                          │
│     → Errors. Failures. Edge cases. Recovery.                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘