povvo/claudikins-github-readme-for-perfectionists/deep-dive

The Deep Dive

Goal: Establish the ground truth of the codebase (what IS) before imagining what could be.

Workflow

Step 0: Load Intelligence Read references/what-to-extract.md for detailed extraction patterns.

1. Scout Structure: List files/dirs to understand layout (bin, src, dist, docs).
2. Identify Configuration: Read dependency files (package.json, Cargo.toml, pyproject.toml).
3. Extract Entry Points: Find main exports, CLI commands, API routes.
4. Context Extraction: Scan chat history for user struggles/intent (if available).
5. Synthesize: Generate the "Codebase Reality Report".

1. Project Type Detection

Entry Point Analysis

Package.json Indicators

{
  "bin": { "cmd": "./dist/cli.js" },     // CLI
  "main": "./dist/index.js",              // Library
  "exports": { ".": "./dist/index.js" },  // Modern library
  "scripts": { "start": "node server.js" } // Application
}

2. Tech Stack Extraction

Dependency Files

Framework Detection

JavaScript/TypeScript:

• react, vue, angular - Frontend framework
• express, fastify, koa - Backend framework
• electron - Desktop app
• react-native - Mobile app

Python:

• fastapi, flask, django - Web framework
• click, typer, argparse - CLI framework
• pytorch, tensorflow - ML framework

Build Tool Detection

3. Dependencies & Prerequisites

Runtime Requirements

From package.json:

{ "engines": { "node": ">=18.0.0", "npm": ">=9.0.0" } }

From pyproject.toml:

[project]
requires-python = ">=3.10"

From Cargo.toml:

[package]
rust-version = "1.70"

System Dependencies

Check these files:

• Dockerfile - RUN apt-get install commands
• .github/workflows/*.yml - setup steps
• Makefile - prerequisite checks
• INSTALL.md or docs/installation.md

Common system deps:

• libssl-dev - cryptography
• libpq-dev - PostgreSQL
• ffmpeg - media processing
• graphviz - diagram generation

4. Entry Points & API Surface

What does the project export/expose?

• Main function/export in index file
• CLI commands from bin directory
• API routes from server files
• Public methods from library exports

CLI help text extraction:

program
  .name('my-tool')
  .description('Process files with advanced filtering')
  .version('1.0.0');

Value proposition sources:

• package.json description field
• Module-level docstrings
• JSDoc on main exports
• Existing README fragments

5. CI/Automation Detection

GitHub Actions

Badge sources from workflows:

• Workflow status - Build badge
• codecov/codecov-action - Coverage badge
• Release workflow - Version badge

Other CI

6. Chat History Context

Source: ~/.claude/history.jsonl

Filter entries where project matches the current project path.

Pattern Extraction

Repeated questions (knowledge gaps):

• "How do I..." patterns
• "Why isn't..." patterns
• "What's the difference between..." patterns

Problem categories:

• Configuration/Setup
• Debugging/Errors
• Feature implementation
• Performance
• Testing
• Deployment

README Implications

Output Format

# Deep Dive Findings
 
## Project Overview
-**Type:** [CLI/library/framework/plugin/app/API]
-**Tech Stack:** [languages, frameworks]
-**Value Proposition:** [1-2 sentence problem/solution]
-**Entry Point:** [main file/command]
 
## Dependencies
-**Runtime:** [Node 18+, Python 3.10+, etc.]
-**System:** [any system dependencies]
-**Dev:** [dev dependencies of note]
 
## Entry Points
-[file:line] - [what it does]
 
## CI/Automation
-**Build:** [workflow files]
-**Badge Sources:** [CI, coverage, package manager]
 
## User Context (from Chat History)
-**Common Struggles:** [repeated questions]
-**Decisions Made:** [key decisions from history]
-**Focus Areas:** [topics frequently discussed]
 
## Missing Information (Blockers)
-[ ] [List anything you need but couldn't find]

Important

• Focus on FACTS, not improvements (that's crystal-ball's job)
• Be specific with file:line references
• Note confidence levels:
• High: Extracted from config files
• Medium: Inferred from patterns
• Low: Guessed from structure

Handoff

After presenting the Reality Report:

1. Ask: "Does this accurately represent the codebase? Any missing information we need to clarify?"
2. Wait for user confirmation.
3. Transition:

• If changes needed: Refine the Deep Dive.
• If approved: "Proceeding to crystal-ball to predict what this project COULD become."