Analysis Codebase

Analyzing Codebase

Overview

Systematically analyze existing codebases to extract structural information. Supports three modes: Context (project characteristics), Brownfield (entities and collision risks), and Setup-Brownfield (comprehensive analysis for /humaninloop:setup).

When to Use

• Setting up constitution on existing codebase (brownfield projects)
• Planning new features against existing code
• Understanding tech stack before making changes
• Detecting collision risks for new entities or endpoints
• Running /humaninloop:setup on projects with existing code
• Gathering project context for governance decisions

When NOT to Use

• Greenfield projects: No existing code to analyze; start with humaninloop:authoring-constitution directly
• Single-file scripts: No architectural patterns to extract
• Documentation-only review: Use standard file reading instead
• Before project directory exists: Nothing to analyze yet
• When user provides complete context: Skip analysis if user already documented tech stack and patterns

Common Mistakes

Mode Selection

Project Type Detection

Identify project type from package manager files:

Framework Detection

Web Frameworks

ORM/Database Frameworks

Architecture Pattern Recognition

Mode: Context Gathering

For constitution authoring - gather broad project characteristics.

What to Extract:

• Tech stack with versions
• Linting/formatting conventions
• CI/CD quality gates
• Team signals (test coverage, required approvals, CODEOWNERS)
• Existing governance docs (CODEOWNERS, ADRs, CONTRIBUTING.md)

Output: Project Context Report (markdown)

See references/CONTEXT-GATHERING.md for detailed guidance.

Mode: Brownfield Analysis

For planning - extract structural details for collision detection.

What to Extract:

• Entities with fields and relationships
• Endpoints with handlers
• Collision risks against proposed spec

Output: Codebase Inventory (JSON)

See references/BROWNFIELD-ANALYSIS.md for detailed guidance.

Mode: Setup Brownfield

For /humaninloop:setup - comprehensive analysis combining Context + Brownfield with Essential Floor assessment.

What to Extract:

• Everything from Context mode (tech stack, conventions, architecture)
• Everything from Brownfield mode (entities, relationships)
• Essential Floor assessment (Security, Testing, Error Handling, Observability)
• Inconsistencies and strengths assessment

Output: .humaninloop/memory/codebase-analysis.md following codebase-analysis-template.md

Essential Floor Analysis

Assess each of the four essential floor categories:

Security Assessment

Indicators to search:

# Auth middleware
grep -r "authenticate\|authorize\|requireAuth\|isAuthenticated" src/ 2>/dev/null

# Environment variables
ls .env.example .env.sample 2>/dev/null
grep -r "process.env\|os.environ\|os.Getenv" src/ 2>/dev/null

# Validation
grep -r "zod\|yup\|joi\|pydantic\|validator" package.json pyproject.toml 2>/dev/null

Testing Assessment

Indicators to search:

# Test config
ls jest.config.* vitest.config.* pytest.ini pyproject.toml 2>/dev/null

# Test files
find . -name "*.test.*" -o -name "*_test.*" -o -name "test_*.*" 2>/dev/null | head -5

# CI test commands
grep -r "npm test\|yarn test\|pytest\|go test" .github/workflows/ 2>/dev/null

Error Handling Assessment

Indicators to search:

# Custom errors
grep -r "class.*Error\|extends Error\|Exception" src/ 2>/dev/null | head -5

# Error logging
grep -r "error.*context\|error.*stack\|logger.error" src/ 2>/dev/null | head -3

# Status codes
grep -r "status(4\|status(5\|HttpStatus\|status_code" src/ 2>/dev/null | head -3

Observability Assessment

Indicators to search:

# Logger config
grep -r "winston\|pino\|structlog\|logrus\|zap" package.json pyproject.toml go.mod 2>/dev/null

# Correlation IDs
grep -r "requestId\|correlationId\|traceId\|x-request-id" src/ 2>/dev/null | head -3

# PII check (negative - should NOT find these in logs)
grep -r "logger.*email\|logger.*password\|log.*password" src/ 2>/dev/null

Setup-Brownfield Quality Checklist

Before finalizing setup-brownfield analysis:

• Project identity complete (name, language, framework, entry points)
• Directory structure documented with purposes
• Architecture pattern identified with evidence
• Naming conventions documented (files, variables, functions, classes)
• All four Essential Floor categories assessed
• Domain entities extracted with relationships
• External dependencies documented
• Strengths to preserve identified (minimum 2-3)
• Inconsistencies documented with severity
• Recommendations provided for constitution focus

Detection Script

Run the automated detection script for fast, deterministic stack identification:

bash scripts/detect-stack.sh /path/to/project

Output:

{
  "project_type": "nodejs",
  "package_manager": "npm",
  "frameworks": ["express"],
  "orms": ["prisma"],
  "architecture": ["feature-based"],
  "ci_cd": ["github-actions"],
  "files_found": {...}
}

The script detects:

• Project type: nodejs, python, go, rust, java, ruby, flutter, elixir
• Package manager: npm, yarn, pnpm, pip, poetry, cargo, etc.
• Frameworks: express, fastapi, django, nextjs, gin, rails, spring-boot, etc.
• ORMs: prisma, typeorm, sqlalchemy, mongoose, gorm, activerecord, etc.
• Architecture: clean-architecture, mvc, layered, feature-based, serverless, microservices
• CI/CD: github-actions, gitlab-ci, jenkins, circleci, etc.

Usage pattern:

1. Run script first for deterministic baseline
2. Use script output to guide deeper LLM analysis
3. Script findings are ground truth; LLM adds nuance

Manual Detection Commands

For cases where script detection is insufficient:

# Tech stack detection
cat package.json | jq '{name, engines, dependencies}'
cat pyproject.toml
cat .tool-versions .nvmrc .python-version 2>/dev/null

# Architecture detection
ls -d src/domain src/application src/features 2>/dev/null

# CI/CD detection
ls .github/workflows/*.yml .gitlab-ci.yml 2>/dev/null

# Governance detection
ls CODEOWNERS .github/CODEOWNERS docs/CODEOWNERS 2>/dev/null
cat CODEOWNERS 2>/dev/null | head -20

# Test structure
ls -d test/ tests/ spec/ __tests__/ 2>/dev/null

Quality Checklist

Before finalizing analysis:

Both Modes:

• Project type and framework correctly identified
• Architecture pattern documented
• File paths cited for all findings

Context Mode:

• Existing linting/formatting config extracted
• CI quality gates analyzed
• Existing governance docs checked (CODEOWNERS, ADRs, CONTRIBUTING.md)
• Approvers identified (from CODEOWNERS or team structure)
• Recommendations provided

Brownfield Mode:

• All entity directories scanned
• All route directories scanned
• Collision risks classified by severity

Setup-Brownfield Mode:

• All Context Mode checks completed
• All four Essential Floor categories assessed
• Strengths and inconsistencies documented
• Output written to .humaninloop/memory/codebase-analysis.md

Related Skills

• For brownfield constitutions: REQUIRED: Use humaninloop:brownfield-constitution after analysis
• For greenfield projects: OPTIONAL: Use humaninloop:authoring-constitution directly
• For validation: OPTIONAL: Use humaninloop:validation-constitution after constitution creation

Converted and distributed by TomeVault — claim your Tome and manage your conversions.