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