Initial commit
This commit is contained in:
Zhongwei Li
381
skills/analyze/operations/completeness-assessment.md
Normal file
381
skills/analyze/operations/completeness-assessment.md
Normal file
@@ -0,0 +1,381 @@
|
||||
# Completeness Assessment
|
||||
|
||||
Assess how complete the application implementation is.
|
||||
|
||||
## Overview
|
||||
|
||||
Estimate the percentage completion for:
|
||||
- Overall application
|
||||
- Backend implementation
|
||||
- Frontend implementation
|
||||
- Test coverage
|
||||
- Documentation
|
||||
- Deployment/Infrastructure
|
||||
|
||||
---
|
||||
|
||||
## Evidence Collection
|
||||
|
||||
### Placeholder Files
|
||||
|
||||
Look for files indicating incomplete work:
|
||||
|
||||
```bash
|
||||
# Find TODO/WIP/PLACEHOLDER files
|
||||
find . -iname "*todo*" -o -iname "*wip*" -o -iname "*placeholder*" -o -iname "*draft*" 2>/dev/null \
|
||||
| grep -v "node_modules\|\.git"
|
||||
|
||||
# Find empty or near-empty files
|
||||
find . -type f -size 0 2>/dev/null | grep -v "node_modules\|\.git\|\.keep"
|
||||
|
||||
# Files with just placeholders
|
||||
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null \
|
||||
| xargs grep -l "TODO\|FIXME\|PLACEHOLDER\|XXX\|HACK" \
|
||||
| head -20
|
||||
```
|
||||
|
||||
### README Mentions
|
||||
|
||||
```bash
|
||||
# Search README for incomplete features
|
||||
grep -i "todo\|wip\|work in progress\|coming soon\|not yet\|planned\|roadmap\|incomplete" README.md 2>/dev/null
|
||||
```
|
||||
|
||||
### Code Comments
|
||||
|
||||
```bash
|
||||
# Count TODO/FIXME comments
|
||||
grep -r "TODO\|FIXME\|XXX\|HACK" src/ 2>/dev/null | wc -l
|
||||
|
||||
# Show sample TODOs
|
||||
grep -r "TODO\|FIXME" src/ 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component-Specific Assessment
|
||||
|
||||
### Backend Completeness
|
||||
|
||||
**Check for:**
|
||||
|
||||
1. **API Endpoints**
|
||||
```bash
|
||||
# Count API routes
|
||||
find . -path "*/api/*" -o -path "*/routes/*" 2>/dev/null | wc -l
|
||||
|
||||
# Find routes with placeholder responses
|
||||
grep -r "res.json({})\|return {}\|NotImplementedError" src/api/ src/routes/ 2>/dev/null
|
||||
```
|
||||
|
||||
2. **Business Logic**
|
||||
```bash
|
||||
# Count service/controller files
|
||||
find . -path "*/services/*" -o -path "*/controllers/*" 2>/dev/null | wc -l
|
||||
|
||||
# Find stub implementations
|
||||
grep -r "throw new Error.*not implemented\|NotImplementedError" src/ 2>/dev/null
|
||||
```
|
||||
|
||||
3. **Database**
|
||||
```bash
|
||||
# Check if migrations are applied
|
||||
ls -la prisma/migrations/ 2>/dev/null | wc -l
|
||||
|
||||
# Check for empty seed files
|
||||
ls -la prisma/seed.ts 2>/dev/null
|
||||
```
|
||||
|
||||
4. **Authentication**
|
||||
```bash
|
||||
# Check for auth middleware
|
||||
find . -name "*auth*" -o -name "*session*" | grep -v node_modules
|
||||
|
||||
# Look for JWT/session handling
|
||||
grep -r "jwt\|jsonwebtoken\|express-session\|passport" package.json src/ 2>/dev/null
|
||||
```
|
||||
|
||||
**Estimate:**
|
||||
- 100% = All endpoints implemented, tested, documented
|
||||
- 75% = All endpoints exist, some missing tests/validation
|
||||
- 50% = Core endpoints done, advanced features missing
|
||||
- 25% = Skeleton only, most logic unimplemented
|
||||
- 0% = No backend implementation
|
||||
|
||||
### Frontend Completeness
|
||||
|
||||
**Check for:**
|
||||
|
||||
1. **Pages/Views**
|
||||
```bash
|
||||
# Count pages
|
||||
find . -path "*/pages/*" -o -path "*/app/*" -o -path "*/views/*" 2>/dev/null \
|
||||
| grep -E "\.(tsx?|jsx?|vue)$" | wc -l
|
||||
|
||||
# Find placeholder pages
|
||||
grep -r "Coming Soon\|Under Construction\|TODO\|Placeholder" app/ pages/ components/ 2>/dev/null
|
||||
```
|
||||
|
||||
2. **Components**
|
||||
```bash
|
||||
# Count components
|
||||
find . -path "*/components/*" | grep -E "\.(tsx?|jsx?|vue)$" | wc -l
|
||||
|
||||
# Find stub components
|
||||
grep -r "return null\|return <div>TODO\|placeholder" components/ 2>/dev/null
|
||||
```
|
||||
|
||||
3. **Styling**
|
||||
```bash
|
||||
# Check for styling setup
|
||||
ls -la tailwind.config.* 2>/dev/null
|
||||
find . -name "*.css" -o -name "*.scss" 2>/dev/null | head -10
|
||||
|
||||
# Check if components are styled
|
||||
grep -r "className\|style=" components/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
4. **State Management**
|
||||
```bash
|
||||
# Check for state management
|
||||
grep -r "redux\|zustand\|recoil\|jotai\|mobx" package.json 2>/dev/null
|
||||
grep -r "createContext\|useContext" src/ app/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
**Estimate:**
|
||||
- 100% = All pages implemented, styled, interactive
|
||||
- 75% = All pages exist, some missing polish/interactivity
|
||||
- 50% = Core pages done, advanced features missing
|
||||
- 25% = Skeleton pages, minimal styling/functionality
|
||||
- 0% = No frontend implementation
|
||||
|
||||
### Testing Completeness
|
||||
|
||||
**Check for:**
|
||||
|
||||
1. **Test Files**
|
||||
```bash
|
||||
# Count test files
|
||||
find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | wc -l
|
||||
|
||||
# Count tests
|
||||
grep -r "test(\|it(\|describe(" tests/ __tests__/ src/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
2. **Test Coverage**
|
||||
```bash
|
||||
# Check for coverage reports
|
||||
ls -la coverage/ 2>/dev/null
|
||||
|
||||
# Check test configuration
|
||||
ls -la jest.config.* vitest.config.* 2>/dev/null
|
||||
```
|
||||
|
||||
3. **Test Types**
|
||||
```bash
|
||||
# Unit tests
|
||||
find . -path "*/tests/unit/*" -o -name "*.unit.test.*" 2>/dev/null | wc -l
|
||||
|
||||
# Integration tests
|
||||
find . -path "*/tests/integration/*" -o -name "*.integration.test.*" 2>/dev/null | wc -l
|
||||
|
||||
# E2E tests
|
||||
find . -path "*/tests/e2e/*" -o -name "*.e2e.*" -o -name "cypress/" -o -name "playwright/" 2>/dev/null
|
||||
```
|
||||
|
||||
**Estimate:**
|
||||
- 100% = >80% code coverage, unit + integration + E2E tests
|
||||
- 75% = 60-80% coverage, unit + integration tests
|
||||
- 50% = 40-60% coverage, mostly unit tests
|
||||
- 25% = <40% coverage, sparse unit tests
|
||||
- 0% = No tests
|
||||
|
||||
### Documentation Completeness
|
||||
|
||||
Use findings from [documentation-scan.md](documentation-scan.md):
|
||||
|
||||
**Estimate:**
|
||||
- 100% = README, API docs, architecture, deployment, developer guide, all current
|
||||
- 75% = README + API docs + some architecture/deployment docs
|
||||
- 50% = Good README, partial API docs
|
||||
- 25% = Basic README only
|
||||
- 0% = No meaningful documentation
|
||||
|
||||
### Infrastructure/Deployment Completeness
|
||||
|
||||
**Check for:**
|
||||
|
||||
1. **Infrastructure as Code**
|
||||
```bash
|
||||
# Check for IaC files
|
||||
find . -name "*.tf" -o -name "serverless.yml" -o -name "cdk.json" 2>/dev/null
|
||||
|
||||
# Count resources defined
|
||||
grep -r "resource\|AWS::" infrastructure/ terraform/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
2. **CI/CD**
|
||||
```bash
|
||||
# GitHub Actions
|
||||
ls -la .github/workflows/ 2>/dev/null
|
||||
|
||||
# Other CI/CD
|
||||
ls -la .gitlab-ci.yml .circleci/config.yml .travis.yml 2>/dev/null
|
||||
```
|
||||
|
||||
3. **Environment Configuration**
|
||||
```bash
|
||||
# Environment files
|
||||
ls -la .env.example .env.template 2>/dev/null
|
||||
|
||||
# Environment validation
|
||||
grep -r "dotenv\|env-var\|envalid" package.json src/ 2>/dev/null
|
||||
```
|
||||
|
||||
4. **Deployment Scripts**
|
||||
```bash
|
||||
# Deployment scripts
|
||||
find . -name "deploy.sh" -o -name "deploy.js" -o -name "deploy.ts" 2>/dev/null
|
||||
|
||||
# Package scripts
|
||||
grep "deploy\|build\|start\|test" package.json 2>/dev/null
|
||||
```
|
||||
|
||||
**Estimate:**
|
||||
- 100% = Full IaC, CI/CD, monitoring, auto-deployment
|
||||
- 75% = IaC + CI/CD, manual deployment
|
||||
- 50% = Basic CI/CD, no IaC
|
||||
- 25% = Manual deployment only
|
||||
- 0% = No deployment setup
|
||||
|
||||
---
|
||||
|
||||
## Overall Completeness Calculation
|
||||
|
||||
Calculate weighted average:
|
||||
|
||||
```
|
||||
Overall = (Backend × 0.3) + (Frontend × 0.3) + (Tests × 0.2) + (Docs × 0.1) + (Infra × 0.1)
|
||||
```
|
||||
|
||||
Example:
|
||||
- Backend: 100%
|
||||
- Frontend: 60%
|
||||
- Tests: 30%
|
||||
- Docs: 40%
|
||||
- Infra: 80%
|
||||
|
||||
Overall = (100 × 0.3) + (60 × 0.3) + (30 × 0.2) + (40 × 0.1) + (80 × 0.1)
|
||||
= 30 + 18 + 6 + 4 + 8
|
||||
= **66%**
|
||||
|
||||
---
|
||||
|
||||
## Missing Components Identification
|
||||
|
||||
List what's missing or incomplete:
|
||||
|
||||
**High Priority:**
|
||||
- [ ] Frontend: User profile page (placeholder only)
|
||||
- [ ] Frontend: Analytics dashboard (not started)
|
||||
- [ ] Backend: Email notification service (stub)
|
||||
- [ ] Tests: Integration tests for API (0 tests)
|
||||
- [ ] Docs: API specification (no OpenAPI)
|
||||
|
||||
**Medium Priority:**
|
||||
- [ ] Frontend: Mobile responsive design (partially done)
|
||||
- [ ] Backend: Rate limiting (not implemented)
|
||||
- [ ] Tests: E2E tests (no framework setup)
|
||||
- [ ] Infra: Monitoring/alerting (not configured)
|
||||
|
||||
**Low Priority:**
|
||||
- [ ] Frontend: Dark mode (placeholder toggle)
|
||||
- [ ] Backend: Admin panel API (not started)
|
||||
- [ ] Docs: Troubleshooting guide (missing)
|
||||
|
||||
---
|
||||
|
||||
## Evidence Summary
|
||||
|
||||
Document the evidence used for estimates:
|
||||
|
||||
```markdown
|
||||
### Evidence
|
||||
|
||||
**Backend (100%):**
|
||||
- 17 Lambda functions fully implemented
|
||||
- All database models defined and migrated
|
||||
- Authentication and authorization complete
|
||||
- API endpoints tested and documented
|
||||
|
||||
**Frontend (60%):**
|
||||
- 8 of 12 planned pages implemented
|
||||
- Core components complete (Header, Footer, Nav)
|
||||
- 4 pages are placeholder/TODO:
|
||||
- Analytics Dashboard (TODO comment in code)
|
||||
- User Settings (returns "Coming Soon")
|
||||
- Admin Panel (not started)
|
||||
- Reports (skeleton only)
|
||||
- Styling ~80% complete
|
||||
|
||||
**Tests (30%):**
|
||||
- 12 unit tests for backend utilities
|
||||
- 0 integration tests
|
||||
- 0 E2E tests
|
||||
- No test coverage reports
|
||||
- jest.config.js exists but minimal tests
|
||||
|
||||
**Documentation (40%):**
|
||||
- Good README with setup instructions
|
||||
- No API documentation (no OpenAPI spec)
|
||||
- No architecture diagrams
|
||||
- Basic deployment guide
|
||||
- No developer guide
|
||||
|
||||
**Infrastructure (80%):**
|
||||
- Full Terraform IaC for AWS
|
||||
- GitHub Actions CI/CD configured
|
||||
- Auto-deploy to staging
|
||||
- Manual production deploy
|
||||
- No monitoring/alerting setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Completeness Assessment
|
||||
|
||||
### Estimated Completion
|
||||
- **Overall:** ~66%
|
||||
- **Backend:** ~100%
|
||||
- **Frontend:** ~60%
|
||||
- **Tests:** ~30%
|
||||
- **Documentation:** ~40%
|
||||
- **Infrastructure:** ~80%
|
||||
|
||||
### Evidence
|
||||
[Detailed evidence as shown above]
|
||||
|
||||
### Missing Components
|
||||
[Categorized list of missing/incomplete features]
|
||||
|
||||
### Placeholder Files
|
||||
- app/analytics/page.tsx (TODO comment)
|
||||
- app/settings/page.tsx ("Coming Soon" text)
|
||||
- src/services/email.ts (stub functions)
|
||||
|
||||
### TODO Comments
|
||||
- Found 23 TODO/FIXME comments across codebase
|
||||
- Most common: Frontend polish, missing tests, error handling
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Be conservative with estimates - round down when uncertain
|
||||
- Provide evidence for all estimates
|
||||
- Consider quality, not just quantity (a poorly implemented feature counts less)
|
||||
- Differentiate between "not started" vs "partially done" vs "mostly complete"
|
||||
268
skills/analyze/operations/detect-stack.md
Normal file
268
skills/analyze/operations/detect-stack.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Tech Stack Detection
|
||||
|
||||
Comprehensive commands for detecting programming languages, frameworks, and build systems.
|
||||
|
||||
## Overview
|
||||
|
||||
Run all detection commands **in parallel** to identify the technology stack. Missing files are normal - they just mean that technology isn't used.
|
||||
|
||||
---
|
||||
|
||||
## Detection Commands
|
||||
|
||||
Execute these commands to detect the primary language and framework:
|
||||
|
||||
```bash
|
||||
# Get current directory context
|
||||
pwd
|
||||
|
||||
# Show directory contents
|
||||
ls -la
|
||||
|
||||
# Get git repository info
|
||||
git remote -v 2>/dev/null
|
||||
|
||||
# Language/Framework Detection (run all in parallel)
|
||||
cat package.json 2>/dev/null # Node.js/JavaScript/TypeScript
|
||||
cat composer.json 2>/dev/null # PHP
|
||||
cat requirements.txt 2>/dev/null # Python (pip)
|
||||
cat Pipfile 2>/dev/null # Python (pipenv)
|
||||
cat pyproject.toml 2>/dev/null # Python (poetry)
|
||||
cat Gemfile 2>/dev/null # Ruby
|
||||
cat pom.xml 2>/dev/null # Java/Maven
|
||||
cat build.gradle 2>/dev/null # Java/Gradle
|
||||
cat Cargo.toml 2>/dev/null # Rust
|
||||
cat go.mod 2>/dev/null # Go
|
||||
cat pubspec.yaml 2>/dev/null # Dart/Flutter
|
||||
cat mix.exs 2>/dev/null # Elixir
|
||||
find . -maxdepth 2 -name "*.csproj" 2>/dev/null # .NET/C#
|
||||
find . -maxdepth 2 -name "*.sln" 2>/dev/null # .NET Solution
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Framework-Specific Detection
|
||||
|
||||
### JavaScript/TypeScript Frameworks
|
||||
|
||||
If `package.json` exists, look for these framework indicators:
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"react": "...", // React
|
||||
"next": "...", // Next.js
|
||||
"vue": "...", // Vue.js
|
||||
"nuxt": "...", // Nuxt.js
|
||||
"@angular/core": "...", // Angular
|
||||
"svelte": "...", // Svelte
|
||||
"express": "...", // Express.js (backend)
|
||||
"fastify": "...", // Fastify (backend)
|
||||
"nestjs": "..." // NestJS (backend)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Python Frameworks
|
||||
|
||||
Look for these imports or dependencies:
|
||||
|
||||
- `django` - Django web framework
|
||||
- `flask` - Flask micro-framework
|
||||
- `fastapi` - FastAPI
|
||||
- `pyramid` - Pyramid
|
||||
- `tornado` - Tornado
|
||||
|
||||
### Ruby Frameworks
|
||||
|
||||
In `Gemfile`:
|
||||
|
||||
- `rails` - Ruby on Rails
|
||||
- `sinatra` - Sinatra
|
||||
- `hanami` - Hanami
|
||||
|
||||
### PHP Frameworks
|
||||
|
||||
In `composer.json`:
|
||||
|
||||
- `laravel/framework` - Laravel
|
||||
- `symfony/symfony` - Symfony
|
||||
- `slim/slim` - Slim
|
||||
|
||||
### Java Frameworks
|
||||
|
||||
In `pom.xml` or `build.gradle`:
|
||||
|
||||
- `spring-boot` - Spring Boot
|
||||
- `quarkus` - Quarkus
|
||||
- `micronaut` - Micronaut
|
||||
|
||||
---
|
||||
|
||||
## Database Detection
|
||||
|
||||
Look for database-related dependencies or configuration:
|
||||
|
||||
### SQL Databases
|
||||
|
||||
```bash
|
||||
# PostgreSQL indicators
|
||||
grep -r "postgres" package.json composer.json requirements.txt 2>/dev/null
|
||||
ls -la prisma/ 2>/dev/null # Prisma ORM
|
||||
|
||||
# MySQL indicators
|
||||
grep -r "mysql" package.json composer.json requirements.txt 2>/dev/null
|
||||
|
||||
# SQLite
|
||||
find . -name "*.db" -o -name "*.sqlite" 2>/dev/null
|
||||
```
|
||||
|
||||
### NoSQL Databases
|
||||
|
||||
```bash
|
||||
# MongoDB
|
||||
grep -r "mongodb\|mongoose" package.json requirements.txt 2>/dev/null
|
||||
|
||||
# Redis
|
||||
grep -r "redis" package.json requirements.txt 2>/dev/null
|
||||
|
||||
# DynamoDB (AWS)
|
||||
grep -r "dynamodb\|@aws-sdk" package.json requirements.txt 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure Detection
|
||||
|
||||
### Cloud Providers
|
||||
|
||||
```bash
|
||||
# AWS
|
||||
find . -name "*.tf" -o -name "terraform.tfvars" 2>/dev/null # Terraform
|
||||
find . -name "serverless.yml" 2>/dev/null # Serverless Framework
|
||||
find . -name "cdk.json" 2>/dev/null # AWS CDK
|
||||
grep -r "@aws-sdk\|aws-lambda" package.json 2>/dev/null
|
||||
|
||||
# Azure
|
||||
grep -r "@azure" package.json 2>/dev/null
|
||||
|
||||
# GCP
|
||||
grep -r "@google-cloud" package.json 2>/dev/null
|
||||
```
|
||||
|
||||
### Container/Orchestration
|
||||
|
||||
```bash
|
||||
# Docker
|
||||
ls -la Dockerfile docker-compose.yml 2>/dev/null
|
||||
|
||||
# Kubernetes
|
||||
find . -name "*.yaml" | xargs grep -l "apiVersion: apps/v1" 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build System Detection
|
||||
|
||||
Identify the build tool based on manifest files:
|
||||
|
||||
- `package.json` → npm, yarn, or pnpm (check for lock files)
|
||||
- `pom.xml` → Maven
|
||||
- `build.gradle` → Gradle
|
||||
- `Cargo.toml` → Cargo (Rust)
|
||||
- `go.mod` → Go modules
|
||||
- `Gemfile` → Bundler
|
||||
- `composer.json` → Composer
|
||||
- `requirements.txt` → pip
|
||||
- `Pipfile` → pipenv
|
||||
- `pyproject.toml` → poetry
|
||||
|
||||
---
|
||||
|
||||
## Version Extraction
|
||||
|
||||
Extract version numbers from manifests:
|
||||
|
||||
```bash
|
||||
# Node.js
|
||||
cat package.json | grep '"version"' | head -1
|
||||
|
||||
# Python
|
||||
cat setup.py | grep "version=" 2>/dev/null
|
||||
cat pyproject.toml | grep "version =" 2>/dev/null
|
||||
|
||||
# Java
|
||||
cat pom.xml | grep "<version>" | head -1
|
||||
|
||||
# Rust
|
||||
cat Cargo.toml | grep "version =" | head -1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language Projects
|
||||
|
||||
If multiple language manifest files exist, identify:
|
||||
|
||||
- **Primary language** - The main application language (most source files)
|
||||
- **Secondary languages** - Supporting tools, scripts, infrastructure
|
||||
|
||||
Example:
|
||||
- Primary: TypeScript (Next.js frontend + backend)
|
||||
- Secondary: Python (data processing scripts), Terraform (infrastructure)
|
||||
|
||||
---
|
||||
|
||||
## Output Summary
|
||||
|
||||
After detection, summarize as:
|
||||
|
||||
```markdown
|
||||
## Technology Stack
|
||||
|
||||
### Primary Language
|
||||
- TypeScript 5.2
|
||||
|
||||
### Frameworks & Libraries
|
||||
- Next.js 14.0.3 (React framework)
|
||||
- Prisma 5.6.0 (ORM)
|
||||
- tRPC 10.45.0 (API)
|
||||
|
||||
### Build System
|
||||
- npm 10.2.3
|
||||
|
||||
### Database
|
||||
- PostgreSQL (via Prisma)
|
||||
|
||||
### Infrastructure
|
||||
- AWS Lambda (Serverless)
|
||||
- Terraform 1.6.0 (IaC)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Full-Stack JavaScript/TypeScript
|
||||
- Frontend: React/Next.js/Vue
|
||||
- Backend: Express/Fastify/NestJS
|
||||
- Database: PostgreSQL/MongoDB
|
||||
- Infrastructure: AWS/Vercel/Netlify
|
||||
|
||||
### Python Web App
|
||||
- Framework: Django/Flask/FastAPI
|
||||
- Database: PostgreSQL/MySQL
|
||||
- Cache: Redis
|
||||
- Infrastructure: AWS/GCP
|
||||
|
||||
### Ruby on Rails
|
||||
- Framework: Rails
|
||||
- Database: PostgreSQL
|
||||
- Cache: Redis
|
||||
- Infrastructure: Heroku/AWS
|
||||
|
||||
### Java Enterprise
|
||||
- Framework: Spring Boot
|
||||
- Database: PostgreSQL/Oracle
|
||||
- Message Queue: RabbitMQ/Kafka
|
||||
- Infrastructure: Kubernetes
|
||||
395
skills/analyze/operations/directory-analysis.md
Normal file
395
skills/analyze/operations/directory-analysis.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# Directory Structure Analysis
|
||||
|
||||
Analyze directory structure to identify architecture patterns and key components.
|
||||
|
||||
## Overview
|
||||
|
||||
Map the directory structure to understand the application's organization and identify:
|
||||
- Architecture patterns (MVC, microservices, monolith, etc.)
|
||||
- Key components (backend, frontend, database, API, infrastructure)
|
||||
- Configuration files
|
||||
- Source code organization
|
||||
|
||||
---
|
||||
|
||||
## Directory Mapping Commands
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```bash
|
||||
# Show directory tree (limited depth to avoid noise)
|
||||
find . -type d -maxdepth 3 | grep -v -E "node_modules|vendor|\.git|build|dist|target|__pycache__|\.next|\.nuxt" | sort | head -50
|
||||
```
|
||||
|
||||
### Configuration Files
|
||||
|
||||
```bash
|
||||
# Find all configuration files
|
||||
find . -maxdepth 3 \( \
|
||||
-name "*.json" -o \
|
||||
-name "*.yaml" -o \
|
||||
-name "*.yml" -o \
|
||||
-name "*.toml" -o \
|
||||
-name "*.xml" -o \
|
||||
-name "*.conf" -o \
|
||||
-name "*.config" -o \
|
||||
-name ".env*" \
|
||||
\) | grep -v -E "node_modules|vendor|\.git|dist|build" | sort | head -40
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Pattern Recognition
|
||||
|
||||
### Frontend Patterns
|
||||
|
||||
**Next.js / React (App Router)**
|
||||
```
|
||||
app/ # Next.js 13+ app directory
|
||||
components/
|
||||
api/
|
||||
(routes)/
|
||||
public/
|
||||
```
|
||||
|
||||
**Next.js (Pages Router)**
|
||||
```
|
||||
pages/ # Next.js pages
|
||||
api/ # API routes
|
||||
components/
|
||||
public/
|
||||
```
|
||||
|
||||
**Standard React**
|
||||
```
|
||||
src/
|
||||
components/
|
||||
hooks/
|
||||
pages/
|
||||
utils/
|
||||
public/
|
||||
```
|
||||
|
||||
**Vue.js**
|
||||
```
|
||||
src/
|
||||
components/
|
||||
views/
|
||||
router/
|
||||
store/
|
||||
public/
|
||||
```
|
||||
|
||||
**Angular**
|
||||
```
|
||||
src/
|
||||
app/
|
||||
components/
|
||||
services/
|
||||
modules/
|
||||
assets/
|
||||
```
|
||||
|
||||
### Backend Patterns
|
||||
|
||||
**Node.js/Express**
|
||||
```
|
||||
src/
|
||||
routes/
|
||||
controllers/
|
||||
models/
|
||||
middleware/
|
||||
services/
|
||||
```
|
||||
|
||||
**NestJS**
|
||||
```
|
||||
src/
|
||||
modules/
|
||||
controllers/
|
||||
services/
|
||||
entities/
|
||||
dto/
|
||||
```
|
||||
|
||||
**Django**
|
||||
```
|
||||
project_name/
|
||||
app_name/
|
||||
models/
|
||||
views/
|
||||
templates/
|
||||
migrations/
|
||||
settings/
|
||||
manage.py
|
||||
```
|
||||
|
||||
**Ruby on Rails**
|
||||
```
|
||||
app/
|
||||
models/
|
||||
controllers/
|
||||
views/
|
||||
helpers/
|
||||
db/
|
||||
migrate/
|
||||
config/
|
||||
```
|
||||
|
||||
### Microservices Pattern
|
||||
|
||||
```
|
||||
services/
|
||||
service-a/
|
||||
service-b/
|
||||
service-c/
|
||||
shared/
|
||||
docker-compose.yml
|
||||
```
|
||||
|
||||
### Monorepo Pattern
|
||||
|
||||
```
|
||||
packages/
|
||||
package-a/
|
||||
package-b/
|
||||
apps/
|
||||
app-1/
|
||||
app-2/
|
||||
turbo.json (or lerna.json, nx.json)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Detection
|
||||
|
||||
### Backend Detection
|
||||
|
||||
Indicators of backend code:
|
||||
|
||||
```bash
|
||||
# API/Backend directories
|
||||
find . -type d -name "api" -o -name "server" -o -name "backend" -o -name "routes" -o -name "controllers" 2>/dev/null
|
||||
|
||||
# Server files
|
||||
find . -name "server.js" -o -name "server.ts" -o -name "app.js" -o -name "app.ts" -o -name "main.py" 2>/dev/null
|
||||
```
|
||||
|
||||
### Frontend Detection
|
||||
|
||||
Indicators of frontend code:
|
||||
|
||||
```bash
|
||||
# Frontend directories
|
||||
find . -type d -name "components" -o -name "pages" -o -name "views" -o -name "public" -o -name "assets" 2>/dev/null
|
||||
|
||||
# Frontend config files
|
||||
find . -name "next.config.*" -o -name "vite.config.*" -o -name "vue.config.*" -o -name "angular.json" 2>/dev/null
|
||||
```
|
||||
|
||||
### Database Detection
|
||||
|
||||
Indicators of database usage:
|
||||
|
||||
```bash
|
||||
# ORM/Database directories
|
||||
find . -type d -name "prisma" -o -name "migrations" -o -name "models" -o -name "entities" 2>/dev/null
|
||||
|
||||
# Database schema files
|
||||
find . -name "schema.prisma" -o -name "*.sql" -o -name "database.yml" 2>/dev/null
|
||||
```
|
||||
|
||||
### Infrastructure Detection
|
||||
|
||||
Indicators of infrastructure-as-code:
|
||||
|
||||
```bash
|
||||
# IaC directories
|
||||
find . -type d -name "terraform" -o -name "infrastructure" -o -name "infra" -o -name ".aws" 2>/dev/null
|
||||
|
||||
# IaC files
|
||||
find . -name "*.tf" -o -name "cloudformation.yml" -o -name "serverless.yml" -o -name "cdk.json" 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Source File Counting
|
||||
|
||||
Count source files by type to understand project size:
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
```bash
|
||||
# TypeScript/JavaScript files (excluding tests, node_modules, build)
|
||||
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) \
|
||||
| grep -v -E "node_modules|dist|build|\.next|coverage|test|spec" \
|
||||
| wc -l
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```bash
|
||||
# Python files
|
||||
find . -type f -name "*.py" \
|
||||
| grep -v -E "__pycache__|venv|\.venv|dist|build|test_" \
|
||||
| wc -l
|
||||
```
|
||||
|
||||
### Java
|
||||
|
||||
```bash
|
||||
# Java files
|
||||
find . -type f -name "*.java" \
|
||||
| grep -v -E "build|target|test" \
|
||||
| wc -l
|
||||
```
|
||||
|
||||
### Ruby
|
||||
|
||||
```bash
|
||||
# Ruby files
|
||||
find . -type f -name "*.rb" \
|
||||
| grep -v -E "vendor|spec|test" \
|
||||
| wc -l
|
||||
```
|
||||
|
||||
### Other Languages
|
||||
|
||||
Adapt the pattern based on detected language:
|
||||
- PHP: `*.php`
|
||||
- Go: `*.go`
|
||||
- Rust: `*.rs`
|
||||
- C#: `*.cs`
|
||||
- Swift: `*.swift`
|
||||
- Kotlin: `*.kt`
|
||||
|
||||
---
|
||||
|
||||
## Key Components Summary
|
||||
|
||||
After analysis, summarize key components:
|
||||
|
||||
```markdown
|
||||
### Key Components Identified
|
||||
|
||||
- **Backend:** Yes - Express.js API server
|
||||
- Location: `src/api/` (12 routes, 8 controllers)
|
||||
- Database: PostgreSQL via Prisma ORM
|
||||
- Authentication: JWT-based
|
||||
|
||||
- **Frontend:** Yes - Next.js 14 with App Router
|
||||
- Location: `app/` (15 pages, 23 components)
|
||||
- Styling: Tailwind CSS
|
||||
- State: React Context + Server Components
|
||||
|
||||
- **Database:** PostgreSQL
|
||||
- ORM: Prisma
|
||||
- Schema: `prisma/schema.prisma` (8 models)
|
||||
- Migrations: 12 migration files
|
||||
|
||||
- **API:** RESTful + tRPC
|
||||
- REST endpoints: `app/api/` (5 routes)
|
||||
- tRPC router: `src/server/api/` (4 routers)
|
||||
- OpenAPI: Not found
|
||||
|
||||
- **Infrastructure:** AWS Serverless
|
||||
- IaC: Terraform (`infrastructure/terraform/`)
|
||||
- Services: Lambda, API Gateway, RDS, S3
|
||||
- CI/CD: GitHub Actions (`.github/workflows/`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Pattern Summary
|
||||
|
||||
Based on directory structure, identify the overall pattern:
|
||||
|
||||
**Examples:**
|
||||
|
||||
- **Monolithic Full-Stack** - Single repo with frontend + backend + database
|
||||
- **Microservices** - Multiple independent services
|
||||
- **JAMstack** - Static frontend + serverless functions + headless CMS
|
||||
- **Serverless** - No traditional servers, all functions/managed services
|
||||
- **Monorepo** - Multiple packages/apps in one repository
|
||||
- **Client-Server** - Clear separation between client and server code
|
||||
|
||||
---
|
||||
|
||||
## Common Directory Structures by Framework
|
||||
|
||||
### Next.js 13+ (App Router)
|
||||
```
|
||||
app/
|
||||
(auth)/
|
||||
login/
|
||||
register/
|
||||
dashboard/
|
||||
api/
|
||||
components/
|
||||
ui/
|
||||
lib/
|
||||
public/
|
||||
prisma/
|
||||
```
|
||||
|
||||
### Next.js (Pages Router)
|
||||
```
|
||||
pages/
|
||||
api/
|
||||
_app.tsx
|
||||
index.tsx
|
||||
components/
|
||||
public/
|
||||
styles/
|
||||
```
|
||||
|
||||
### Express.js Backend
|
||||
```
|
||||
src/
|
||||
routes/
|
||||
controllers/
|
||||
models/
|
||||
middleware/
|
||||
services/
|
||||
utils/
|
||||
config/
|
||||
tests/
|
||||
```
|
||||
|
||||
### Django
|
||||
```
|
||||
project/
|
||||
app/
|
||||
models.py
|
||||
views.py
|
||||
urls.py
|
||||
serializers.py
|
||||
settings/
|
||||
wsgi.py
|
||||
manage.py
|
||||
requirements.txt
|
||||
```
|
||||
|
||||
### Rails
|
||||
```
|
||||
app/
|
||||
models/
|
||||
controllers/
|
||||
views/
|
||||
jobs/
|
||||
mailers/
|
||||
db/
|
||||
migrate/
|
||||
config/
|
||||
routes.rb
|
||||
Gemfile
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Exclude common noise directories: node_modules, vendor, .git, dist, build, target, __pycache__, .next, .nuxt, coverage
|
||||
- Limit depth to 3 levels to avoid overwhelming output
|
||||
- Use `head` to limit file counts for large codebases
|
||||
- Look for naming conventions that indicate purpose (e.g., `controllers/`, `services/`, `utils/`)
|
||||
367
skills/analyze/operations/documentation-scan.md
Normal file
367
skills/analyze/operations/documentation-scan.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Documentation Scan
|
||||
|
||||
Scan for existing documentation and assess quality.
|
||||
|
||||
## Overview
|
||||
|
||||
Identify all existing documentation to understand:
|
||||
- What's already documented
|
||||
- Quality and completeness of docs
|
||||
- What documentation is missing
|
||||
- Where docs are located
|
||||
|
||||
---
|
||||
|
||||
## Documentation Discovery
|
||||
|
||||
### Find Documentation Directories
|
||||
|
||||
```bash
|
||||
# Common documentation directories
|
||||
ls -la docs/ 2>/dev/null
|
||||
ls -la documentation/ 2>/dev/null
|
||||
ls -la doc/ 2>/dev/null
|
||||
ls -la wiki/ 2>/dev/null
|
||||
ls -la .docs/ 2>/dev/null
|
||||
```
|
||||
|
||||
### Find Markdown Files
|
||||
|
||||
```bash
|
||||
# Find all markdown files (limiting to avoid noise)
|
||||
find . -type f -name "*.md" \
|
||||
| grep -v -E "node_modules|vendor|\.git|dist|build" \
|
||||
| head -30
|
||||
```
|
||||
|
||||
### Common Documentation Files
|
||||
|
||||
Look for these standard files:
|
||||
|
||||
```bash
|
||||
# Standard docs
|
||||
ls -la README.md 2>/dev/null
|
||||
ls -la CONTRIBUTING.md 2>/dev/null
|
||||
ls -la CHANGELOG.md 2>/dev/null
|
||||
ls -la LICENSE 2>/dev/null
|
||||
ls -la CODE_OF_CONDUCT.md 2>/dev/null
|
||||
ls -la SECURITY.md 2>/dev/null
|
||||
|
||||
# Setup/deployment docs
|
||||
ls -la INSTALL.md 2>/dev/null
|
||||
ls -la DEPLOYMENT.md 2>/dev/null
|
||||
ls -la SETUP.md 2>/dev/null
|
||||
|
||||
# Architecture docs
|
||||
ls -la ARCHITECTURE.md 2>/dev/null
|
||||
ls -la DESIGN.md 2>/dev/null
|
||||
ls -la API.md 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Categories
|
||||
|
||||
### README Assessment
|
||||
|
||||
Read `README.md` and assess quality:
|
||||
|
||||
**Good README includes:**
|
||||
- Clear project description
|
||||
- Installation/setup instructions
|
||||
- Usage examples
|
||||
- API documentation or links
|
||||
- Development guide
|
||||
- Testing instructions
|
||||
- Deployment guide
|
||||
- Contributing guidelines
|
||||
- License information
|
||||
|
||||
**Rate as:**
|
||||
- **Good** - Comprehensive, well-organized, covers all key areas
|
||||
- **Basic** - Has description and setup, but missing key sections
|
||||
- **Poor** - Minimal info, outdated, or confusing
|
||||
|
||||
### API Documentation
|
||||
|
||||
Look for API documentation:
|
||||
|
||||
```bash
|
||||
# OpenAPI/Swagger
|
||||
find . -name "openapi.yaml" -o -name "openapi.yml" -o -name "swagger.yaml" -o -name "swagger.json" 2>/dev/null
|
||||
|
||||
# API doc generators
|
||||
find . -name "apidoc.json" -o -name ".redocly.yaml" 2>/dev/null
|
||||
|
||||
# API docs directories
|
||||
ls -la docs/api/ 2>/dev/null
|
||||
ls -la api-docs/ 2>/dev/null
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - OpenAPI spec or comprehensive API docs exist
|
||||
- **Partial** - Some API docs but incomplete
|
||||
- **No** - No API documentation found
|
||||
|
||||
### Architecture Documentation
|
||||
|
||||
Look for architecture diagrams and docs:
|
||||
|
||||
```bash
|
||||
# Architecture docs
|
||||
find . -name "ARCHITECTURE.md" -o -name "architecture.md" -o -name "DESIGN.md" 2>/dev/null
|
||||
|
||||
# Diagram files
|
||||
find . \( -name "*.drawio" -o -name "*.mermaid" -o -name "*.puml" -o -name "*.svg" \) \
|
||||
| grep -i "architecture\|diagram\|flow" 2>/dev/null
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - Architecture docs with diagrams/explanations
|
||||
- **Partial** - Some architecture info in README
|
||||
- **No** - No architecture documentation
|
||||
|
||||
### Setup/Deployment Documentation
|
||||
|
||||
```bash
|
||||
# Deployment docs
|
||||
find . -name "DEPLOYMENT.md" -o -name "deployment.md" -o -name "DEPLOY.md" 2>/dev/null
|
||||
|
||||
# Infrastructure docs
|
||||
ls -la infrastructure/README.md 2>/dev/null
|
||||
ls -la terraform/README.md 2>/dev/null
|
||||
ls -la .github/workflows/ 2>/dev/null
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - Clear deployment and infrastructure docs
|
||||
- **Partial** - Basic setup but missing details
|
||||
- **No** - No deployment documentation
|
||||
|
||||
### Developer Documentation
|
||||
|
||||
```bash
|
||||
# Developer guides
|
||||
find . -name "CONTRIBUTING.md" -o -name "DEVELOPMENT.md" -o -name "dev-guide.md" 2>/dev/null
|
||||
|
||||
# Code comments/JSDoc
|
||||
grep -r "@param\|@returns\|@description" src/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - Developer guide with setup, conventions, workflow
|
||||
- **Partial** - Some developer info scattered
|
||||
- **No** - No developer documentation
|
||||
|
||||
### Testing Documentation
|
||||
|
||||
```bash
|
||||
# Test docs
|
||||
find . -name "TESTING.md" -o -name "test-guide.md" 2>/dev/null
|
||||
|
||||
# Test README files
|
||||
find . -path "*/tests/README.md" -o -path "*/test/README.md" 2>/dev/null
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - Testing guide with examples and conventions
|
||||
- **Partial** - Basic test info in README
|
||||
- **No** - No testing documentation
|
||||
|
||||
### Database Documentation
|
||||
|
||||
```bash
|
||||
# Database docs
|
||||
find . -name "schema.md" -o -name "database.md" -o -name "DATA_MODEL.md" 2>/dev/null
|
||||
|
||||
# ER diagrams
|
||||
find . -name "*er-diagram*" -o -name "*schema-diagram*" 2>/dev/null
|
||||
|
||||
# Migration docs
|
||||
ls -la migrations/README.md 2>/dev/null
|
||||
ls -la prisma/README.md 2>/dev/null
|
||||
```
|
||||
|
||||
**Assessment:**
|
||||
- **Yes** - Database schema docs and ER diagrams
|
||||
- **Partial** - Schema file but no explanatory docs
|
||||
- **No** - No database documentation
|
||||
|
||||
---
|
||||
|
||||
## Documentation Tools Detection
|
||||
|
||||
Identify if automated documentation tools are configured:
|
||||
|
||||
### Code Documentation Generators
|
||||
|
||||
```bash
|
||||
# JSDoc/TypeDoc (JavaScript/TypeScript)
|
||||
grep -r "typedoc\|jsdoc" package.json 2>/dev/null
|
||||
|
||||
# Sphinx (Python)
|
||||
ls -la docs/conf.py 2>/dev/null
|
||||
|
||||
# Javadoc (Java)
|
||||
grep -r "javadoc" pom.xml build.gradle 2>/dev/null
|
||||
|
||||
# RDoc/YARD (Ruby)
|
||||
ls -la .yardopts 2>/dev/null
|
||||
|
||||
# Doxygen (C/C++)
|
||||
ls -la Doxyfile 2>/dev/null
|
||||
```
|
||||
|
||||
### API Documentation Tools
|
||||
|
||||
```bash
|
||||
# Swagger UI
|
||||
grep -r "swagger-ui" package.json 2>/dev/null
|
||||
|
||||
# Redoc
|
||||
grep -r "redoc" package.json 2>/dev/null
|
||||
|
||||
# Postman collections
|
||||
find . -name "*.postman_collection.json" 2>/dev/null
|
||||
```
|
||||
|
||||
### Static Site Generators
|
||||
|
||||
```bash
|
||||
# Docusaurus
|
||||
grep -r "docusaurus" package.json 2>/dev/null
|
||||
ls -la docusaurus.config.js 2>/dev/null
|
||||
|
||||
# VuePress
|
||||
grep -r "vuepress" package.json 2>/dev/null
|
||||
|
||||
# MkDocs
|
||||
ls -la mkdocs.yml 2>/dev/null
|
||||
|
||||
# GitBook
|
||||
ls -la .gitbook.yaml 2>/dev/null
|
||||
|
||||
# Mintlify
|
||||
ls -la mint.json 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Quality Checklist
|
||||
|
||||
For each category, assess:
|
||||
|
||||
- [ ] **Exists** - Documentation files are present
|
||||
- [ ] **Current** - Docs match current code (check dates)
|
||||
- [ ] **Complete** - Covers all major features/components
|
||||
- [ ] **Clear** - Well-written and easy to understand
|
||||
- [ ] **Examples** - Includes code examples and usage
|
||||
- [ ] **Maintained** - Recently updated (check git log)
|
||||
|
||||
---
|
||||
|
||||
## Output Summary
|
||||
|
||||
Summarize findings:
|
||||
|
||||
```markdown
|
||||
## Existing Documentation
|
||||
|
||||
### README.md
|
||||
- **Status:** Yes
|
||||
- **Quality:** Good
|
||||
- **Coverage:** Installation, usage, API overview, development setup
|
||||
- **Last Updated:** 2024-01-15
|
||||
- **Notes:** Comprehensive but missing deployment section
|
||||
|
||||
### API Documentation
|
||||
- **Status:** Partial
|
||||
- **Type:** Inline JSDoc comments only
|
||||
- **Coverage:** ~60% of endpoints documented
|
||||
- **OpenAPI Spec:** No
|
||||
- **Notes:** Should generate OpenAPI spec
|
||||
|
||||
### Architecture Documentation
|
||||
- **Status:** No
|
||||
- **Notes:** Architecture decisions are scattered in code comments
|
||||
|
||||
### Setup/Deployment Documentation
|
||||
- **Status:** Yes
|
||||
- **Files:** DEPLOYMENT.md, infrastructure/README.md
|
||||
- **Coverage:** AWS deployment, CI/CD, environment setup
|
||||
- **Quality:** Basic
|
||||
|
||||
### Developer Documentation
|
||||
- **Status:** Partial
|
||||
- **Files:** CONTRIBUTING.md
|
||||
- **Coverage:** PR process, code style guide
|
||||
- **Missing:** Local development setup, debugging guide
|
||||
|
||||
### Testing Documentation
|
||||
- **Status:** No
|
||||
- **Notes:** No testing guide, test structure undocumented
|
||||
|
||||
### Database Documentation
|
||||
- **Status:** Yes
|
||||
- **Type:** Prisma schema file with comments
|
||||
- **Coverage:** All models documented inline
|
||||
- **ER Diagram:** No
|
||||
- **Notes:** Should generate ER diagram from schema
|
||||
|
||||
### Documentation Tools
|
||||
- **Configured:** None
|
||||
- **Recommended:** TypeDoc for code docs, Swagger for API docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Missing Documentation Identification
|
||||
|
||||
List what documentation should be created:
|
||||
|
||||
**Critical (needed for Step 2):**
|
||||
- OpenAPI specification for API endpoints
|
||||
- Architecture overview document
|
||||
- Database ER diagram
|
||||
|
||||
**Important (create during specification):**
|
||||
- Comprehensive testing guide
|
||||
- Deployment runbook
|
||||
- Troubleshooting guide
|
||||
|
||||
**Nice-to-have:**
|
||||
- Code contribution guide
|
||||
- ADRs (Architecture Decision Records)
|
||||
- Security documentation
|
||||
|
||||
---
|
||||
|
||||
## Documentation Metrics
|
||||
|
||||
Calculate documentation coverage:
|
||||
|
||||
```bash
|
||||
# Count documented vs undocumented functions (example for JS/TS)
|
||||
# Total functions
|
||||
grep -r "function\|const.*=>.*{" src/ | wc -l
|
||||
|
||||
# Documented functions (with JSDoc)
|
||||
grep -B1 "function\|const.*=>" src/ | grep -c "/\*\*"
|
||||
|
||||
# Calculate percentage
|
||||
```
|
||||
|
||||
Report as:
|
||||
- **Code documentation coverage:** ~45% (estimated)
|
||||
- **API endpoint documentation:** ~60%
|
||||
- **Feature documentation:** ~30%
|
||||
- **Overall documentation score:** 4/10
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Check git history to see when docs were last updated
|
||||
- Compare doc dates with code changes to identify stale docs
|
||||
- Look for TODO/FIXME comments in docs indicating incomplete sections
|
||||
- Verify links in docs aren't broken
|
||||
475
skills/analyze/operations/generate-report.md
Normal file
475
skills/analyze/operations/generate-report.md
Normal file
@@ -0,0 +1,475 @@
|
||||
# Generate Analysis Report
|
||||
|
||||
Template and guidelines for creating `analysis-report.md`.
|
||||
|
||||
## Overview
|
||||
|
||||
After completing all analysis steps, generate a comprehensive `analysis-report.md` file in the project root.
|
||||
|
||||
---
|
||||
|
||||
## Report Template
|
||||
|
||||
```markdown
|
||||
# Initial Analysis Report
|
||||
|
||||
**Date:** [Current Date - YYYY-MM-DD]
|
||||
**Directory:** [Full path from pwd]
|
||||
**Analyst:** Claude Code (Reverse Engineering Toolkit v1.0.0)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 paragraph summary of the application, its purpose, current state, and overall completeness]
|
||||
|
||||
Example:
|
||||
> This is a full-stack Next.js application for managing aquarium fish care ("fishfan"). The backend is fully implemented with 17 AWS Lambda functions, PostgreSQL database, and complete authentication. The frontend is ~60% complete with core functionality implemented but several pages still in placeholder state. Overall project completion is estimated at ~66%.
|
||||
|
||||
---
|
||||
|
||||
## Application Metadata
|
||||
|
||||
- **Name:** [Application Name from package.json or directory]
|
||||
- **Version:** [Version from manifest]
|
||||
- **Description:** [From manifest or README]
|
||||
- **Repository:** [Git remote URL or "Not configured"]
|
||||
- **License:** [From LICENSE file or package.json]
|
||||
- **Primary Language:** [Language] [Version if available]
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Primary Language
|
||||
- [Language] [Version]
|
||||
- [Key notes about language usage]
|
||||
|
||||
### Frontend Framework
|
||||
- [Framework] [Version]
|
||||
- [Key dependencies and notes]
|
||||
|
||||
### Backend Framework
|
||||
- [Framework] [Version]
|
||||
- [Key dependencies and notes]
|
||||
|
||||
### Database
|
||||
- [Database Type] [Version/Service]
|
||||
- ORM: [ORM if applicable]
|
||||
- Migration System: [Yes/No with details]
|
||||
|
||||
### Infrastructure & Deployment
|
||||
- **Cloud Provider:** [AWS/GCP/Azure/Other]
|
||||
- **IaC Tool:** [Terraform/CloudFormation/CDK/None]
|
||||
- **CI/CD:** [GitHub Actions/GitLab CI/CircleCI/None]
|
||||
- **Hosting:** [Vercel/Netlify/AWS Lambda/EC2/etc.]
|
||||
|
||||
### Key Dependencies
|
||||
|
||||
| Category | Library | Version | Purpose |
|
||||
|----------|---------|---------|---------|
|
||||
| Auth | [Library] | [Version] | [Purpose] |
|
||||
| API | [Library] | [Version] | [Purpose] |
|
||||
| UI | [Library] | [Version] | [Purpose] |
|
||||
| Testing | [Library] | [Version] | [Purpose] |
|
||||
| Build | [Library] | [Version] | [Purpose] |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Application Type
|
||||
[Full-Stack Monolith / Microservices / JAMstack / Serverless / etc.]
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
[Project Root]/
|
||||
├── [key-directory-1]/ # [Purpose]
|
||||
│ ├── [subdirectory]/ # [Purpose]
|
||||
│ └── ...
|
||||
├── [key-directory-2]/ # [Purpose]
|
||||
├── [configuration-files] # [Purpose]
|
||||
└── [other-key-files]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
#### Backend
|
||||
- **Status:** [Exists / Not Found]
|
||||
- **Location:** [Directory path]
|
||||
- **Type:** [REST API / GraphQL / tRPC / Mixed]
|
||||
- **Endpoints:** [Count] endpoints identified
|
||||
- **Database Models:** [Count] models
|
||||
- **Authentication:** [Method - JWT/Session/OAuth/None]
|
||||
- **Key Features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
|
||||
#### Frontend
|
||||
- **Status:** [Exists / Not Found]
|
||||
- **Location:** [Directory path]
|
||||
- **Type:** [SPA / SSR / SSG / Hybrid]
|
||||
- **Pages:** [Count] pages identified
|
||||
- **Components:** [Count] reusable components
|
||||
- **Styling:** [Tailwind/CSS Modules/Styled Components/etc.]
|
||||
- **State Management:** [Redux/Context/Zustand/None]
|
||||
- **Key Features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
|
||||
#### Database
|
||||
- **Type:** [PostgreSQL/MySQL/MongoDB/etc.]
|
||||
- **ORM:** [Prisma/TypeORM/Sequelize/etc.]
|
||||
- **Schema Location:** [Path to schema files]
|
||||
- **Models:** [Count] models defined
|
||||
- **Migrations:** [Count] migrations
|
||||
- **Seeding:** [Configured / Not Configured]
|
||||
|
||||
#### API Architecture
|
||||
- **Type:** [RESTful / GraphQL / tRPC / Mixed]
|
||||
- **Endpoints:** [Count] total endpoints
|
||||
- **Documentation:** [OpenAPI Spec / Inline Comments / None]
|
||||
- **Versioning:** [v1/v2/etc. or None]
|
||||
- **Rate Limiting:** [Configured / Not Configured]
|
||||
|
||||
#### Infrastructure
|
||||
- **IaC Tool:** [Terraform/CloudFormation/etc.]
|
||||
- **Services Used:**
|
||||
- [Service 1]: [Purpose]
|
||||
- [Service 2]: [Purpose]
|
||||
- [Service 3]: [Purpose]
|
||||
- **Configuration:** [Location of IaC files]
|
||||
- **Environments:** [dev/staging/prod or single]
|
||||
|
||||
---
|
||||
|
||||
## Existing Documentation
|
||||
|
||||
### README.md
|
||||
- **Status:** [Yes / No]
|
||||
- **Quality:** [Good / Basic / Poor]
|
||||
- **Sections:**
|
||||
- [✓] Description
|
||||
- [✓] Installation
|
||||
- [✗] API Documentation
|
||||
- [✓] Development Setup
|
||||
- [✗] Testing Guide
|
||||
- [✓] Deployment
|
||||
- **Last Updated:** [Date from git log]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### API Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Format:** [OpenAPI/Postman/Inline/None]
|
||||
- **Coverage:** [Percentage or count]
|
||||
- **Location:** [Path or URL]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Architecture Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Files:** [List of architecture docs]
|
||||
- **Diagrams:** [Yes/No - list types]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Setup/Deployment Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Files:** [List files]
|
||||
- **Coverage:** [What's documented]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Developer Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Files:** [CONTRIBUTING.md, etc.]
|
||||
- **Coverage:** [What's documented]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Testing Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Files:** [Test guide files]
|
||||
- **Coverage:** [What's documented]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Database Documentation
|
||||
- **Status:** [Yes / Partial / No]
|
||||
- **Type:** [ER Diagram / Schema Comments / None]
|
||||
- **Coverage:** [What's documented]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
### Documentation Tools
|
||||
- **Configured:** [List tools like TypeDoc, JSDoc, Sphinx, etc.]
|
||||
- **Output Location:** [Where docs are generated]
|
||||
- **Notes:** [Any observations]
|
||||
|
||||
---
|
||||
|
||||
## Completeness Assessment
|
||||
|
||||
### Overall Completion: ~[X]%
|
||||
|
||||
### Component Breakdown
|
||||
|
||||
| Component | Completion | Evidence |
|
||||
|-----------|------------|----------|
|
||||
| Backend | ~[X]% | [Brief evidence] |
|
||||
| Frontend | ~[X]% | [Brief evidence] |
|
||||
| Database | ~[X]% | [Brief evidence] |
|
||||
| Tests | ~[X]% | [Brief evidence] |
|
||||
| Documentation | ~[X]% | [Brief evidence] |
|
||||
| Infrastructure | ~[X]% | [Brief evidence] |
|
||||
|
||||
### Detailed Evidence
|
||||
|
||||
#### Backend (~[X]%)
|
||||
[Detailed evidence with specific examples, file counts, etc.]
|
||||
|
||||
Example:
|
||||
- 17 Lambda functions fully implemented and tested
|
||||
- All API endpoints functional with proper error handling
|
||||
- Authentication/authorization complete with JWT
|
||||
- Database queries optimized
|
||||
- No placeholder or TODO comments in backend code
|
||||
|
||||
#### Frontend (~[X]%)
|
||||
[Detailed evidence]
|
||||
|
||||
Example:
|
||||
- 8 of 12 planned pages implemented
|
||||
- Core pages complete: Login, Dashboard, Fish List, Fish Detail
|
||||
- Placeholder pages: Analytics (TODO), Settings (stub), Admin (not started), Reports (skeleton)
|
||||
- Components: 23 reusable components, all functional
|
||||
- Styling: ~80% complete, missing dark mode and mobile polish
|
||||
|
||||
#### Tests (~[X]%)
|
||||
[Detailed evidence]
|
||||
|
||||
#### Documentation (~[X]%)
|
||||
[Detailed evidence]
|
||||
|
||||
#### Infrastructure (~[X]%)
|
||||
[Detailed evidence]
|
||||
|
||||
### Placeholder Files & TODOs
|
||||
|
||||
**Files with Placeholder Content:**
|
||||
- [File path]: [Description]
|
||||
- [File path]: [Description]
|
||||
|
||||
**TODO/FIXME Comments:**
|
||||
- Found [N] TODO comments across codebase
|
||||
- Top categories:
|
||||
1. [Category]: [Count]
|
||||
2. [Category]: [Count]
|
||||
3. [Category]: [Count]
|
||||
|
||||
**Sample TODOs:**
|
||||
```
|
||||
[File:Line] - TODO: [Comment]
|
||||
[File:Line] - FIXME: [Comment]
|
||||
[File:Line] - TODO: [Comment]
|
||||
```
|
||||
|
||||
### Missing Components
|
||||
|
||||
**Not Started:**
|
||||
- [Component/Feature]: [Description]
|
||||
- [Component/Feature]: [Description]
|
||||
|
||||
**Partially Implemented:**
|
||||
- [Component/Feature]: [What exists vs what's missing]
|
||||
- [Component/Feature]: [What exists vs what's missing]
|
||||
|
||||
**Needs Improvement:**
|
||||
- [Component/Feature]: [Current state and what needs work]
|
||||
- [Component/Feature]: [Current state and what needs work]
|
||||
|
||||
---
|
||||
|
||||
## Source Code Statistics
|
||||
|
||||
- **Total Source Files:** [Count]
|
||||
- **Lines of Code:** ~[Estimate from cloc or wc]
|
||||
- **Test Files:** [Count]
|
||||
- **Test Coverage:** [Percentage if available or "Not measured"]
|
||||
- **Configuration Files:** [Count]
|
||||
|
||||
### File Type Breakdown
|
||||
|
||||
| Type | Count | Purpose |
|
||||
|------|-------|---------|
|
||||
| TypeScript/JavaScript | [Count] | [Application code/Components/etc.] |
|
||||
| Tests | [Count] | [Unit/Integration/E2E] |
|
||||
| Styles | [Count] | [CSS/SCSS/etc.] |
|
||||
| Configuration | [Count] | [Build/Deploy/Environment] |
|
||||
| Documentation | [Count] | [Markdown files] |
|
||||
|
||||
---
|
||||
|
||||
## Technical Debt & Issues
|
||||
|
||||
### Identified Issues
|
||||
1. [Issue 1]: [Description and impact]
|
||||
2. [Issue 2]: [Description and impact]
|
||||
3. [Issue 3]: [Description and impact]
|
||||
|
||||
### Security Concerns
|
||||
- [Concern 1]: [Description]
|
||||
- [Concern 2]: [Description]
|
||||
|
||||
### Performance Concerns
|
||||
- [Concern 1]: [Description]
|
||||
- [Concern 2]: [Description]
|
||||
|
||||
### Code Quality
|
||||
- Linting: [Configured / Not Configured]
|
||||
- Type Checking: [Strict / Loose / None]
|
||||
- Code Formatting: [Prettier/ESLint/None]
|
||||
- Pre-commit Hooks: [Configured / Not Configured]
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
Based on this analysis, the reverse engineering process should focus on:
|
||||
|
||||
### Immediate Priorities
|
||||
1. **[Priority 1]**
|
||||
- Why: [Reasoning]
|
||||
- Impact: [Expected outcome]
|
||||
|
||||
2. **[Priority 2]**
|
||||
- Why: [Reasoning]
|
||||
- Impact: [Expected outcome]
|
||||
|
||||
3. **[Priority 3]**
|
||||
- Why: [Reasoning]
|
||||
- Impact: [Expected outcome]
|
||||
|
||||
### Reverse Engineering Focus Areas
|
||||
|
||||
For **Step 2 (Reverse Engineer)**:
|
||||
- Prioritize extracting documentation for: [List components]
|
||||
- Pay special attention to: [Areas of concern]
|
||||
- Can likely skip: [Well-documented areas]
|
||||
|
||||
### Estimated Reverse Engineering Effort
|
||||
- **Step 2 (Reverse Engineer):** ~[X] minutes (based on codebase size)
|
||||
- **Step 3 (Create Specifications):** ~[X] minutes
|
||||
- **Step 4 (Gap Analysis):** ~[X] minutes
|
||||
- **Step 5 (Complete Specification):** ~[X] minutes (interactive)
|
||||
- **Step 6 (Implement from Spec):** ~[X] hours/days (depends on gaps)
|
||||
|
||||
---
|
||||
|
||||
## Notes & Observations
|
||||
|
||||
[Any additional observations, concerns, or context that doesn't fit above categories]
|
||||
|
||||
Examples:
|
||||
- Monorepo structure detected but not using workspace tools
|
||||
- Multiple authentication methods suggest migration in progress
|
||||
- Infrastructure code is more mature than application code
|
||||
- Build process is complex and could be simplified
|
||||
- Dependencies are up-to-date (as of [date])
|
||||
|
||||
---
|
||||
|
||||
## Appendices
|
||||
|
||||
### A. Dependency Tree (Top-Level)
|
||||
|
||||
```
|
||||
[Main dependencies with versions]
|
||||
```
|
||||
|
||||
### B. Configuration Files Inventory
|
||||
|
||||
```
|
||||
[List of all configuration files with brief descriptions]
|
||||
```
|
||||
|
||||
### C. Database Schema Summary
|
||||
|
||||
```
|
||||
[List of models/tables with key relationships]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Report Generated:** [Timestamp]
|
||||
**Toolkit Version:** 1.0.0
|
||||
**Ready for Step 2:** ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filling Out the Template
|
||||
|
||||
### Executive Summary Guidelines
|
||||
|
||||
Write a 2-3 paragraph summary answering:
|
||||
1. What is this application? (Purpose, domain, users)
|
||||
2. What's the tech stack? (Key technologies)
|
||||
3. What's the current state? (Completion %, what's done, what's missing)
|
||||
4. What's next? (Main recommendation)
|
||||
|
||||
### Evidence Requirements
|
||||
|
||||
For every percentage estimate, provide concrete evidence:
|
||||
- File counts
|
||||
- Feature lists
|
||||
- Specific examples
|
||||
- Code samples (for TODOs)
|
||||
- Dates (for documentation)
|
||||
|
||||
### Prioritization Logic
|
||||
|
||||
Recommend next steps based on:
|
||||
1. **Critical gaps** - Security, data integrity, deployment blockers
|
||||
2. **High-value gaps** - User-facing features, core functionality
|
||||
3. **Quality gaps** - Tests, documentation, error handling
|
||||
4. **Nice-to-haves** - Polish, optimizations, extras
|
||||
|
||||
---
|
||||
|
||||
## Report Validation Checklist
|
||||
|
||||
Before finalizing the report, verify:
|
||||
|
||||
- [ ] All sections filled out (no [TODO] markers left)
|
||||
- [ ] Percentages are evidence-based, not guesses
|
||||
- [ ] File paths are accurate and up-to-date
|
||||
- [ ] Tech stack versions are correct
|
||||
- [ ] Missing components are clearly identified
|
||||
- [ ] Recommendations are actionable
|
||||
- [ ] Executive summary is clear and concise
|
||||
- [ ] Report is saved to project root as `analysis-report.md`
|
||||
|
||||
---
|
||||
|
||||
## Sample Output Location
|
||||
|
||||
The report should be saved to:
|
||||
```
|
||||
/path/to/project-root/analysis-report.md
|
||||
```
|
||||
|
||||
This ensures it's:
|
||||
- Easy to find
|
||||
- Version controlled (add to git)
|
||||
- Referenced by subsequent steps
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Report
|
||||
|
||||
Once the report is generated and reviewed:
|
||||
|
||||
1. **Review with user** - Present key findings
|
||||
2. **Confirm accuracy** - Ask if the analysis matches their understanding
|
||||
3. **Adjust estimates** - Update based on user feedback
|
||||
4. **Proceed to Step 2** - Use the reverse-engineer skill to generate comprehensive documentation
|
||||
|
||||
The analysis report serves as the foundation for the entire reverse engineering process.
|
||||
Reference in New Issue
Block a user