Codebase Discovery (As-Is)

Produce a comprehensive, evidence-backed model of an existing codebase's actual architecture. This skill reads real code, traces real dependencies, and maps real data flows — never relying on documentation claims without verification. Every statement in the output must cite [file:line] evidence.

When to Use This Skill

• After creating a Review Brief, to build the factual foundation for analysis
• When inheriting a codebase and need to understand what actually exists
• When documentation is suspected to be out of date or incomplete
• As input to Reverse PRD, Gap Analysis, or any downstream brownfield skill

Pipeline Position

[REVIEW_BRIEF.md + ALIGNMENT_MATRIX.md + Codebase] --> **CODEBASE DISCOVERY (AS-IS)** --> [AS_IS_SYSTEM_MODEL.md] --> Reverse PRD --> ...

Input: REVIEW_BRIEF.md, ALIGNMENT_MATRIX.md, actual codebase (via Read/Glob/Grep) Output: AS_IS_SYSTEM_MODEL.md written to artifacts directory

Artifact Template

The output artifact follows the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read Review Brief and Alignment Matrix

1. Read REVIEW_BRIEF.md to understand scope, goals, and constraints
2. Read ALIGNMENT_MATRIX.md to understand which codebase areas map to which goals
3. Extract the list of in-scope directories, files, and modules
4. Note the analysis methods assigned to each goal-area mapping

Step 2: Enumerate Project Structure

1. Glob for all top-level directories and files in the codebase root
2. Glob for source directories one level deeper to understand module boundaries
3. Record directory tree (depth 3) showing the organizational skeleton
4. Classify directories by purpose:
   • Source code (src/, lib/, app/, pkg/)
   • Tests (tests/, __tests__/, spec/, test/)
   • Configuration (config/, .github/, deploy/)
   • Build artifacts (dist/, build/, target/, out/)
   • Documentation (docs/, doc/)
   • Static assets (public/, static/, assets/)
   • Database (migrations/, seeds/, fixtures/)
5. Cite evidence: > Source code organized in src/ directory [src/:directory]

Step 3: Detect Technology Stack

Scan for technology indicators and record with version evidence.

1. Package manifests (read each found file):

   • package.json -> Node.js/npm ecosystem, extract dependencies, devDependencies, engines
   • requirements.txt / pyproject.toml / setup.py / Pipfile -> Python ecosystem
   • Cargo.toml -> Rust ecosystem, extract [dependencies]
   • go.mod -> Go ecosystem, extract module path and require block
   • pom.xml / build.gradle / build.gradle.kts -> JVM ecosystem
   • *.csproj / *.sln -> .NET ecosystem
   • Gemfile -> Ruby ecosystem
   • Package.swift -> Swift ecosystem
   • composer.json -> PHP ecosystem

2. Framework detection (Grep for framework-specific patterns):

   • Web frameworks: Express, FastAPI, Django, Rails, Spring, Gin, Actix, ASP.NET
   • Frontend frameworks: React, Vue, Angular, Svelte, Next.js, Nuxt
   • ORM/Database: Prisma, SQLAlchemy, TypeORM, Sequelize, ActiveRecord, GORM, Diesel
   • Testing: Jest, pytest, JUnit, RSpec, go test, cargo test

3. Infrastructure detection:

   • Dockerfile / docker-compose.yml -> Containerization
   • terraform/ / *.tf -> Infrastructure as Code
   • k8s/ / kubernetes/ / *.yaml with kind: -> Kubernetes
   • .github/workflows/ -> GitHub Actions CI/CD
   • serverless.yml / sam-template.yaml -> Serverless

4. Record technology table:

| Technology | Version | Evidence | Purpose |
|-----------|---------|----------|---------|
| Node.js | 18.x | [package.json:4] | Runtime |
| TypeScript | 5.3.2 | [package.json:18] | Language |
| Express | 4.18.2 | [package.json:12] | HTTP framework |

Step 4: Build Component Inventory

Identify discrete components, modules, or services in the codebase.

1. Identify component boundaries:

   • Top-level source directories often represent components
   • Packages/modules with their own manifest files
   • Services in monorepo structures
   • Microservice boundaries (separate Dockerfiles, separate entry points)

2. For each component, record:

   • Component ID: COMP-NNNN (sorted alphabetically by component name)
   • Name: Human-readable name
   • Path: Root directory relative to project root
   • Type: Service | Library | Module | Package | Worker | CLI | UI
   • Entry point: Main file that bootstraps or exports the component [file:line]
   • Responsibility: One-sentence summary of what this component does
   • Technology: Primary language/framework
   • Lines of code: Approximate (from file count and average size)
   • Test presence: Yes/No with path to test directory

3. Grep for entry points:

   • main(), app.listen(), createServer(), if __name__, func main(), fn main()
   • Export aggregation files (index.ts, __init__.py, mod.rs)
   • CLI entry points (bin/, shebang lines)

Step 5: Trace Dependencies

Map inter-component and external dependencies.

1. Internal dependencies (between components):

   • Grep for import/require statements across component boundaries
   • Track which components depend on which others
   • Identify circular dependencies
   • Record: COMP-0001 --> COMP-0003 [src/api/routes.ts:5]

2. External dependencies (third-party):

   • Parse package manifest dependencies section
   • Categorize: Runtime | Development | Optional | Peer
   • Flag deprecated or known-vulnerable packages if version is detectable
   • Count total: direct and transitive (if lock file exists)

3. Dependency Mermaid diagram:

```mermaid
graph TD
    COMP-0001[API Gateway] --> COMP-0002[Auth Service]
    COMP-0001 --> COMP-0003[Data Layer]
    COMP-0002 --> COMP-0003
    COMP-0003 --> ext_db[(PostgreSQL)]
    COMP-0001 --> ext_cache[(Redis)]

4. **Circular dependency detection**:
   - If A imports B and B imports A (directly or transitively), flag as a finding
   - Record cycle chain with file evidence

### Step 6: Map Data Flows

Trace how data enters, transforms, and exits the system.

1. **Entry points**: HTTP routes, CLI arguments, message queue consumers, file watchers, cron jobs
   - Grep for route definitions: `app.get`, `@app.route`, `router.Handle`, `#[get]`
   - Grep for queue consumers: `subscribe`, `consume`, `on('message'`
   - Record each with `[file:line]` evidence

2. **Data transformations**:
   - Model/schema definitions (Grep for class/interface/struct definitions in model directories)
   - Validation layers (Grep for validation libraries: Joi, Zod, Pydantic, serde)
   - Serialization/deserialization points

3. **Exit points**: HTTP responses, database writes, queue publishes, file writes, external API calls
   - Grep for: `res.send`, `res.json`, `return Response`, `db.insert`, `publish`, `fetch(`, `axios`
   - Record each with `[file:line]` evidence

4. **Data flow Mermaid diagram**:
```markdown
```mermaid
flowchart LR
    Client -->|HTTP| API[API Layer]
    API -->|Validate| Service[Service Layer]
    Service -->|Query| DB[(Database)]
    Service -->|Publish| Queue[Message Queue]
    Queue -->|Consume| Worker[Background Worker]
    Worker -->|Write| Storage[File Storage]

### Step 7: Identify Configuration and Environment

1. **Configuration files**: Grep for config loading patterns
   - Environment variables: `process.env`, `os.environ`, `os.Getenv`, `std::env`
   - Config files: `.env`, `config/`, `application.yml`, `settings.py`
   - Feature flags: LaunchDarkly, Unleash, custom flag systems

2. **Environment separation**:
   - Development, staging, production configs
   - Environment-specific overrides
   - Secret management approach (env vars, vault, config files)

3. **Record configuration inventory**:
```markdown
| Config Source | Type | Evidence | Secrets Present |
|--------------|------|----------|-----------------|
| .env | Environment variables | [.env.example:1-15] | Yes (redacted) |
| config/database.yml | YAML config | [config/database.yml:1] | Connection strings |

Step 8: Compile As-Is System Model

Assemble all findings into the final artifact.

1. Write AS_IS_SYSTEM_MODEL.md following the template
2. Verify every claim has [file:line] citation
3. Flag any areas where evidence was inconclusive as Open Questions
4. Cross-reference with ALIGNMENT_MATRIX.md to ensure all mapped areas are covered

Output Format

AS_IS_SYSTEM_MODEL.md Structure

# As-Is System Model: [Project Name]

## Summary
[3-5 sentence evidence-backed overview of the system as it exists today]

## Inputs
- REVIEW_BRIEF.md
- ALIGNMENT_MATRIX.md
- Codebase at: [path]

## Outputs
- AS_IS_SYSTEM_MODEL.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption with rationale]

## Open Questions
- [OQ-NNNN]: [Question about unclear or unverifiable aspects]

## Main Content

### System Overview
> [Evidence-backed description] [file:line]

### Technology Stack
| Technology | Version | Evidence | Purpose |
|-----------|---------|----------|---------|

### Component Inventory
#### COMP-0001: [Name]
- **Path**: [relative path]
- **Type**: [Service | Library | Module | ...]
- **Entry Point**: [file:line]
- **Responsibility**: [description]
- **Test Coverage**: [Yes/No, path]

### Dependency Map
```mermaid
[Component dependency diagram]

Internal Dependencies

From	To	Evidence	Type

External Dependencies

Package	Version	Category	Evidence

Circular Dependencies

[List or "None detected"]

Data Flow

[Data flow diagram]

Entry Points

Type	Path/Pattern	Handler	Evidence

Exit Points

Type	Destination	Handler	Evidence

Configuration and Environment

Config Source	Type	Evidence	Notes

Evidence Index

[Consolidated list of all file:line citations organized by section]

Acceptance Criteria

• Every claim cites [file:line] evidence
• Component inventory covers all in-scope source directories
• Dependency map includes both internal and external dependencies
• Data flow traces entry to exit for primary paths
• Technology stack lists versions with manifest evidence
• Mermaid diagrams render correctly
• Open Questions capture all unverifiable claims

**Output path**: `artifacts/brownfield/<project_name>/AS_IS_SYSTEM_MODEL.md`

## Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. **COMP-NNNN IDs**: Sort all components alphabetically by component name (case-insensitive), then assign sequential four-digit numbers starting at 0001
2. **Technology table rows**: Sort alphabetically by Technology column
3. **Dependency table rows**: Sort by From component ID, then by To component ID
4. **Entry/Exit point rows**: Sort by Type, then by Path/Pattern alphabetically
5. **Configuration rows**: Sort by Config Source alphabetically
6. **Sections**: Always in template order, never reordered
7. **No timestamps**: Do not include generation timestamps in artifact body
8. **Mermaid node IDs**: Use COMP-NNNN IDs as node identifiers for consistency
9. **Evidence Index**: Sort by section heading, then by file path alphabetically

## Evidence Citation Rules

Every architectural claim, observation, or assertion about the codebase MUST include evidence citations.

**Format**: `> Claim text [relative/path/to/file.ext:line_number]`

**Examples**:
```markdown
> The API server listens on port 3000 by default [src/server.ts:45]
> Database models use Prisma ORM with PostgreSQL provider [prisma/schema.prisma:3-5]
> Authentication uses bcrypt for password hashing [src/auth/hash.ts:12]
> Worker processes Redis queue jobs every 30 seconds [src/workers/processor.ts:8]

Rules:

• Single line reference: [file:line]
• Range reference: [file:start-end]
• Multiple files: [file1:line] [file2:line]
• Directory reference (for structural claims): [directory/:structure]
• If a claim cannot be evidenced, prefix with [UNVERIFIED] and add to Open Questions

Quality Checklist

Before finalizing the artifact, verify:

• Every factual claim about the codebase has [file:line] citation
• Component inventory accounts for all in-scope source directories from ALIGNMENT_MATRIX.md
• Technology stack versions are sourced from manifest files, not assumed
• Dependency diagram includes all COMP-NNNN components
• Data flow covers at least the primary request path (entry to exit)
• No documentation claims used as evidence without code verification
• Circular dependencies either listed or explicitly noted as absent
• Configuration inventory distinguishes secrets from non-secrets
• Open Questions capture any gap between what was mapped and what was expected
• COMP-NNNN IDs sorted alphabetically by name
• Mermaid diagrams use valid syntax and render correctly
• Evidence Index consolidates all citations for traceability

Error Handling

• REVIEW_BRIEF.md not found: Report error; this skill requires the review brief as input. Direct user to run review-brief-alignment first
• Codebase path invalid or empty: Report error with path attempted; do not generate speculative models
• No manifest files found: Record as Open Question; proceed with file extension and directory structure analysis only
• Binary files or compiled artifacts: Skip; note in Assumptions that analysis covers source files only
• Monorepo with multiple projects: Treat each project root as a separate component; note monorepo structure in System Overview
• Obfuscated or minified code: Skip; note in Assumptions and flag in Open Questions