12 KiB
12 KiB
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
# 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:
- What is this application? (Purpose, domain, users)
- What's the tech stack? (Key technologies)
- What's the current state? (Completion %, what's done, what's missing)
- 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:
- Critical gaps - Security, data integrity, deployment blockers
- High-value gaps - User-facing features, core functionality
- Quality gaps - Tests, documentation, error handling
- 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:
- Review with user - Present key findings
- Confirm accuracy - Ask if the analysis matches their understanding
- Adjust estimates - Update based on user feedback
- 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.