gh-devkade-collaborator-skills-oss-contribution-framework/assets/templates/codebase-notes-template.md

Codebase Exploration Notes: [Project Name]

Repository: [URL or path] Explored: [date] For Issue: #[number] Language: [primary language]

---

Quick Reference

Essential Commands:

# Install dependencies
[command]

# Run dev server
[command]

# Run tests
[command]

# Lint/format
[command]

Key Directories:

• Source: [path]
• Tests: [path]
• Docs: [path]

---

Project Summary

[2-3 sentences about what this project does and how it's structured]

Purpose: [What problem does this solve?]

Target Users: [Developer tool / Web app / Library / CLI / etc]

Core Technologies:

• Language: [language + version]
• Framework: [if applicable]
• Build tool: [tool]
• Testing: [framework]

Project Maturity:

• Age: [years or months]
• Activity: [active / moderate / slow]
• Contributors: [approximate count]
• Stability: [alpha / beta / stable / mature]

---

Directory Structure

project-root/
├── [main-source-dir]/     - [purpose]
├── [test-dir]/            - [purpose]
├── [docs-dir]/            - [purpose]
├── [config-files]         - [purpose]
└── [other-key-dirs]/      - [purpose]

Organization Principle:

• By feature (users/, products/, orders/)
• By layer (models/, views/, controllers/)
• By type (components/, utils/, services/)
• Hybrid approach

Notes: [Any special organization patterns or unusual directory purposes]

---

Code Conventions

Naming Conventions

Files:

• Pattern: [kebab-case / PascalCase / snake_case]
• Extensions: [.js, .ts, .tsx, etc]
• Tests: [*.test.js / test.go / test.py]

Code Elements:

• Classes: [PascalCase]
• Functions: [camelCase / snake_case]
• Variables: [camelCase / snake_case]
• Constants: [UPPER_SNAKE_CASE / kConstant]
• Private: [_private / #private / __private]

Examples from codebase:

// Actual examples from the project
class ExampleClass { }
function exampleFunction() { }
const EXAMPLE_CONSTANT = 'value'

Code Style

Formatting:

• Indentation: [2 spaces / 4 spaces / tabs]
• Line length: [80 / 100 / 120 chars]
• Quotes: [single / double]
• Semicolons: [required / optional]

Imports:

// Import order example from project
import external from 'package'
import internal from '@/internal'
import relative from './relative'

Comments:

• Documentation: [JSDoc / docstrings / rustdoc / etc]
• Inline: [when and how used]
• TODO format: [TODO: / TODO(name): / FIXME:]

Error Handling:

• Pattern: [try/catch / Result<T,E> / error codes]
• Custom errors: [how defined]
• Error messages: [format and style]

Architectural Patterns

Overall Pattern: [MVC / MVVM / Layered / Component-based / etc]

State Management: [How application state is managed]

Data Flow: [How data moves through the system]

Dependency Direction: [e.g., UI → Services → Data Layer]

Key Abstractions:

• [Abstraction 1]: [purpose and how used]
• [Abstraction 2]: [purpose and how used]

---

Testing

Test Framework & Location

Framework: [Jest / pytest / JUnit / etc]

Test Locations:

• Unit tests: [path pattern]
• Integration tests: [path pattern]
• E2E tests: [path pattern]

Test Naming:

• Pattern: [describe/it / test_ / Test* / #[test]]
• Convention: [naming style for test descriptions]

Test Structure

Typical test pattern:

// Example test structure from the project
describe('FeatureName', () => {
  it('should do X when Y', () => {
    // Arrange
    // Act
    // Assert
  })
})

Common patterns:

• Setup/teardown: [how handled]
• Fixtures: [location and usage]
• Mocks: [how created]
• Assertions: [library and style]

Running Tests

# All tests
[command]

# Specific file
[command]

# With coverage
[command]

# Watch mode
[command]

Coverage:

• Target: [percentage if specified]
• Tool: [coverage tool used]
• Reports: [where generated]

---

Development Workflow

Setup

# Initial setup
git clone [repo]
cd [project]
[install command]
[setup environment]

Prerequisites:

• [Tool/version requirement 1]
• [Tool/version requirement 2]

Development Commands

# Development mode
[command]

# Build
[command]

# Lint
[command]

# Format
[command]

# Type check (if applicable)
[command]

Git Workflow

Branch naming: [pattern: feature/, fix/, etc]

Commit format:

type(scope): description

[longer explanation if needed]

Pre-commit hooks:

• [What runs automatically]

---

CI/CD

CI System: [GitHub Actions / Travis / CircleCI / etc]

Configuration: [.github/workflows/* / .travis.yml / etc]

CI Checks:

• Tests
• Linting
• Type checking
• Build
• Coverage
• [Other checks]

Important: [Any CI-specific considerations]

---

Reference Examples

For My Work

Similar features/patterns:

1. [Feature/Pattern 1]

   • File: [path/to/file]:[line]
   • What it does: [description]
   • Why relevant: [how it relates to my issue]
   • Pattern to follow: [specific pattern]

2. [Feature/Pattern 2]

   • File: [path/to/file]:[line]
   • What it does: [description]
   • Why relevant: [how it relates]
   • Pattern to follow: [specific pattern]

3. [Feature/Pattern 3]

   • File: [path/to/file]:[line]
   • What it does: [description]
   • Why relevant: [how it relates]

Patterns to Replicate

• [Pattern 1]: [e.g., how errors are handled]

  • Example: [file:line]
  • Apply to: [my use case]

• [Pattern 2]: [e.g., how validation is done]

  • Example: [file:line]
  • Apply to: [my use case]

• [Pattern 3]: [e.g., how tests are structured]

  • Example: [file:line]
  • Apply to: [my use case]

Patterns to Avoid

• [Anti-pattern 1]: [old code being refactored]
• [Anti-pattern 2]: [special case, don't generalize]

---

Impact Analysis

Files I'll Likely Modify

1. [path/to/file1]

   • Reason: [why this file]
   • Change type: [add / modify / delete]
   • Confidence: [high / medium / low]

2. [path/to/file2]

   • Reason: [why this file]
   • Change type: [add / modify / delete]
   • Confidence: [high / medium / low]

Dependencies to Consider

Upstream (what calls my changes):

Downstream (what my changes call):

Side effects:

• File I/O
• Network calls
• Database operations
• State mutations
• Event emissions

Risk Level

Overall risk: 🟢 Low / 🟡 Medium / 🔴 High

Risk factors:

• [Factor 1: e.g., modifying critical path]
• [Factor 2: e.g., poorly tested area]

Mitigation:

• [Strategy 1: e.g., add extra tests]
• [Strategy 2: e.g., incremental changes]

---

Notes & Questions

Key Observations

• [Observation 1: interesting pattern or consideration]
• [Observation 2: something to remember]
• [Observation 3: potential challenge]

Still Unclear

• [Question 1: what still needs investigation]
• [Question 2: clarification needed]
• [Question 3: uncertainty]

Resources

• Documentation: [links to relevant docs]
• Similar issues: [links to related issues/PRs]
• References: [external resources]

---

Next Steps

✅ Exploration complete - Ready for Phase 4: Issue-Code Mapping

Recommended focus:

1. [Specific file/component to examine more closely]
2. [Pattern to understand deeper]
3. [Test to review as reference]

Action items:

• [Specific exploration task if needed]
• [Question to ask maintainer if needed]
• [Code to trace if needed]

---

Personal Notes

[Any additional thoughts, reminders, or insights for myself]