moicle 2.0.0 → 2.1.0

package/assets/skills/research/onboarding/SKILL.md

@@ -5,7 +5,7 @@ description: Codebase onboarding workflow for understanding new projects. Use wh
 
 # Codebase Onboarding Workflow
 
-Complete workflow for understanding and navigating new codebases effectively.
+Ramp up on a new codebase quickly: structure, conventions, where things live, how to make a first change.
 
 ## When to use this skill
 
@@ -18,572 +18,189 @@ Complete workflow for understanding and navigating new codebases effectively.
 
 ## Read Architecture First
 
-Read `ddd-architecture.md` + stack-specific doc first. Architecture context speeds up codebase comprehension dramatically.
+Detect stack with `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + the stack doc. Architecture context speeds up everything below by 10x.
 
-## Workflow Overview
+---
+
+## Workflow
 
 ```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ 1. SCAN  │──▶│ 2. ANALYZE──▶│ 3. EXPLAIN──▶│ 4. GUIDE │
-└──────────┘   └──────────┘   └──────────┘   └──────────┘
-     │              │               │              │
-     └──────────────┴───────────────┴──────────────┘
-              Comprehensive Understanding
+SCAN → ANALYZE → EXPLAIN → GUIDE (first commit checklist)
 ```
 
 ---
 
-## Phase 1: SCAN
-
-**Goal**: Get a quick overview of project structure and tech stack
-
-### Actions
-1. Identify project type and stack:
-   ```bash
-   # Check package files
-   ls -la | grep -E "package.json|pubspec.yaml|go.mod|composer.json|requirements.txt"
-
-   # Check framework markers
-   ls -la | grep -E "next.config|vite.config|angular.json|remix.config"
-   ```
-
-2. **Identify and read the appropriate architecture doc** based on stack
-
-3. Scan directory structure:
-   ```bash
-   tree -L 2 -I 'node_modules|vendor|dist|build|.git'
-   # or
-   ls -R | grep ":$" | sed -e 's/:$//' -e 's/[^-][^\/]*\//--/g'
-   ```
+## Phase 1: SCAN (10-20 min)
 
-4. Check tech stack and dependencies:
-   - `package.json` (Node.js/JS)
-   - `pubspec.yaml` (Flutter)
-   - `go.mod` (Go)
-   - `composer.json` (PHP/Laravel)
-   - `requirements.txt` (Python)
+**Goal:** map the territory before reading any business code.
 
-5. Look for documentation:
-   - README.md
-   - CONTRIBUTING.md
-   - docs/ directory
-   - .claude/architecture/ (project-specific)
+```bash
+# Structure
+tree -L 2 -I 'node_modules|vendor|dist|build|.git'
 
-### Output Template
-```markdown
-## Project Scan Results
+# Tech surface
+ls -la | grep -E "package.json|pubspec.yaml|go.mod|composer.json|Dockerfile|Makefile"
 
-### Stack Identification
-- **Primary Language**: [JavaScript/TypeScript/Dart/Go/PHP/Python]
-- **Framework**: [React/Flutter/Gin/Laravel/Django/etc]
-- **Architecture Doc**: [path to applicable architecture reference]
-- **Build Tool**: [Vite/Webpack/Maven/Gradle/etc]
-- **Package Manager**: [npm/bun/yarn/pub/go mod/composer]
+# Existing docs
+find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" -o -name "ARCHITECTURE*"
 
-### Directory Structure
-```
-project/
-├── src/              # [description based on architecture doc]
-├── tests/            # [testing structure]
-├── config/           # [configuration]
-└── docs/             # [documentation]
+# Activity
+git log --oneline -20
+git shortlog -sn --since=3months | head -10
 ```
 
-### Key Dependencies (Top 5)
-1. [dependency] - [purpose]
-2. [dependency] - [purpose]
-3. [dependency] - [purpose]
-
-### Documentation Available
-- [ ] README.md
-- [ ] Architecture docs (.claude/architecture/)
-- [ ] API documentation
-- [ ] Contributing guide
-```
+### Capture
+- Top-level layout (≤2 levels)
+- Tech stack + main dependencies (5-10 biggest)
+- Existing docs found (read in next phase)
+- Active contributors + recent commit themes
 
 ### Gate
-- [ ] Stack identified
-- [ ] Architecture doc read
-- [ ] Directory structure mapped
-- [ ] Dependencies listed
+- [ ] Stack detected (or asked user if ambiguous)
+- [ ] Top-level structure understood
+- [ ] Existing docs inventoried
 
 ---
 
-## Phase 2: ANALYZE
-
-**Goal**: Deep dive into architecture, patterns, and conventions
-
-### Actions
-1. **Analyze architecture based on the reference doc**:
-   - Identify layers (from architecture doc)
-   - Find data flow patterns (from architecture doc)
-   - Map dependency injection patterns (from architecture doc)
+## Phase 2: ANALYZE (30-60 min)
 
-2. **Identify code patterns and conventions**:
-   ```bash
-   # Find main entry points
-   grep -r "main\|index\|app" --include="*.{js,ts,dart,go,php,py}"
+**Goal:** understand layer boundaries, conventions, and the "shape" of code.
 
-   # Find common patterns
-   grep -r "class\|interface\|type\|struct" --include="*.{js,ts,dart,go,php}"
-
-   # Find state management
-   grep -r "useState\|Provider\|Redux\|Riverpod\|Bloc" --include="*.{js,ts,dart}"
-   ```
-
-3. **Analyze configuration**:
-   - Environment variables (.env, .env.example)
-   - Config files (config/, .config/)
-   - Build configuration
-
-4. **Check testing setup**:
-   - Test framework (Jest, Vitest, PHPUnit, Go test)
-   - Test directory structure
-   - Coverage setup
-
-5. **Review code quality setup**:
-   - Linter configuration (.eslintrc, analysis_options.yaml)
-   - Formatter (prettier, gofmt, php-cs-fixer)
-   - Pre-commit hooks
-
-### Analysis Output
-```markdown
-## Architecture Analysis
-
-### Reference Document
-**Architecture Doc**: [path]
-**Pattern**: [Clean Architecture/MVVM/MVC/etc]
-
-### Layer Structure (from architecture doc)
-1. **[Layer 1 - e.g., Presentation]**
-   - Location: [directory path]
-   - Responsibilities: [from doc]
-   - Key files: [list]
-
-2. **[Layer 2 - e.g., Domain]**
-   - Location: [directory path]
-   - Responsibilities: [from doc]
-   - Key files: [list]
-
-3. **[Layer 3 - e.g., Data]**
-   - Location: [directory path]
-   - Responsibilities: [from doc]
-   - Key files: [list]
-
-### Data Flow (from architecture doc)
-```
-[User Input] → [Presentation] → [Domain] → [Data] → [External APIs/DB]
-              ←                ←          ←
-```
+### Read in this order
+1. `README.md` — purpose + setup
+2. `ARCHITECTURE.md` / `CONTRIBUTING.md` if present
+3. **One existing module end-to-end** — pick the smallest with a full layer stack (e.g., `domain/user/`). Trace: entity → port → usecase → handler → test.
+4. Cross-domain wiring (event bus / DI / router registration)
+5. CI config (`.github/workflows/`, `Makefile`) — what's enforced?
 
-### Key Patterns Identified
-- **State Management**: [pattern used]
-- **Dependency Injection**: [pattern used]
-- **Routing**: [pattern used]
-- **API Communication**: [pattern used]
-- **Error Handling**: [pattern used]
-
-### Naming Conventions
-- **Files**: [convention - kebab-case, snake_case, PascalCase]
-- **Classes**: [convention]
-- **Functions**: [convention]
-- **Constants**: [convention]
-
-### Code Quality
-- **Linter**: [ESLint/Dart Analyzer/golangci-lint/etc]
-- **Formatter**: [Prettier/dartfmt/gofmt/etc]
-- **Testing**: [Jest/PHPUnit/Go test/etc]
-- **Coverage Target**: [percentage if specified]
-
-### Configuration
-- **Environment Variables**: [.env location and key vars]
-- **Config Files**: [list important configs]
-- **Build Config**: [description]
-```
+### Capture
+- Architecture pattern (DDD / MVC / clean / hexagonal — match against `ddd-architecture.md`)
+- Naming conventions (file, function, test)
+- Where business logic lives (usecase vs service vs handler)
+- How errors are returned (typed, panics, error wrapping)
+- Test framework + folder convention
+- How code reaches prod (CI checks, release process)
 
 ### Gate
-- [ ] Architecture pattern identified (matches doc)
-- [ ] Layers mapped (per architecture doc)
-- [ ] Code conventions documented
-- [ ] Testing setup understood
+- [ ] One module read end-to-end
+- [ ] Layer boundaries understood
+- [ ] Test + CI conventions known
 
 ---
 
 ## Phase 3: EXPLAIN
 
-**Goal**: Generate comprehensive documentation/explanation
-
-### Actions
-1. **Create architectural overview** following the reference doc
-2. **Document key components** in each layer
-3. **Map common workflows** (how data flows through layers)
-4. **List important files** and their purposes
-5. **Document setup process**
+**Goal:** produce a 1-page mental model that someone else can read.
 
-### Explanation Template
 ```markdown
-## Codebase Explanation
+## Project: {name}
 
-### Project Overview
-**Name**: [project name]
-**Purpose**: [what it does]
-**Stack**: [tech stack]
-**Architecture**: [pattern - with reference to doc]
-
----
+### Purpose
+{1-2 sentences: what business problem this solves}
 
-### Architecture Overview
+### Stack
+- Language: {go 1.22 / node 20 / dart 3.x / ...}
+- Framework: {gin / nestjs / remix / flutter ...}
+- DB: {postgres + sqlc / prisma / eloquent ...}
+- Infra: {docker, k8s on GKE, redis, kafka ...}
 
-This project follows **[architecture pattern from doc]**
+### Architecture
+{1 sentence: e.g., "DDD with hexagonal — domain-pure, infra implements ports"}
 
-#### Directory Structure Explained
 ```
-project/
-├── [layer1]/              # [Purpose based on architecture doc]
-│   ├── [component]/       # [Specific purpose]
-│   └── [component]/       # [Specific purpose]
-├── [layer2]/              # [Purpose based on architecture doc]
-│   ├── [component]/       # [Specific purpose]
-│   └── [component]/       # [Specific purpose]
-└── [layer3]/              # [Purpose based on architecture doc]
-    ├── [component]/       # [Specific purpose]
-    └── [component]/       # [Specific purpose]
+{ascii or mermaid: top-level layer diagram}
 ```
 
----
-
-### Key Components
-
-#### 1. [Component Name]
-- **Location**: [path]
-- **Layer**: [which layer from architecture doc]
-- **Purpose**: [what it does]
-- **Key Files**:
-  - `[file1]` - [purpose]
-  - `[file2]` - [purpose]
-- **Dependencies**: [what it depends on]
+### Domains
+| Domain | Responsibility |
+|--------|----------------|
+| {name} | {one line} |
 
-#### 2. [Component Name]
-- **Location**: [path]
-- **Layer**: [which layer from architecture doc]
-- **Purpose**: [what it does]
-- **Key Files**:
-  - `[file1]` - [purpose]
-  - `[file2]` - [purpose]
-- **Dependencies**: [what it depends on]
+### Where to find things
+| If you need to... | Look in |
+|-------------------|---------|
+| Add a route | `application/ports/http/<domain>_handler` |
+| Add business logic | `domain/<domain>/usecases` |
+| Add a DB query | `infrastructure/database/<domain>_store` |
+| Add a domain event | `domain/<domain>/events` + register in event bus |
+| Add a test | `*_test.go` next to the source file |
 
-(Repeat for top 5-10 components)
+### Conventions
+- Error handling: {pattern}
+- Logging: {library + level convention}
+- Config: {env vars / yaml / both}
+- Branch / commit: {convention}
 
----
-
-### Common Workflows
-
-#### Workflow 1: [e.g., User Authentication]
-```
-1. User enters credentials in [Presentation Layer Component]
-2. [UseCase/Service] validates input
-3. [Repository/Data Source] calls API
-4. Response flows back through layers
-5. UI updates with result
+### Gotchas
+- {anything surprising — e.g., "cache TTL is 30s, not 5 min like the comment says"}
 ```
 
-**Files Involved**:
-- [file1] - [role]
-- [file2] - [role]
-- [file3] - [role]
-
-#### Workflow 2: [e.g., Data Fetching]
-```
-[Describe step by step following architecture layers]
-```
-
-**Files Involved**:
-- [file1] - [role]
-- [file2] - [role]
-
----
-
-### Important Files Reference
-
-#### Core Files
-- `[file]` - [purpose]
-- `[file]` - [purpose]
-
-#### Configuration
-- `[file]` - [purpose]
-- `[file]` - [purpose]
-
-#### Entry Points
-- `[file]` - [main entry]
-- `[file]` - [test entry]
+### Gate
+- [ ] 1-page mental model written
+- [ ] "Where to find things" table covers ≥5 common tasks
+- [ ] At least 1 gotcha documented (every codebase has them)
 
 ---
 
-### Setup & Development
-
-#### Installation
-```bash
-# [step-by-step installation based on project]
-```
+## Phase 4: GUIDE — first commit checklist
 
-#### Development Commands
-```bash
-# Start dev server
-[command]
+**Goal:** unblock the first real change. The fastest ramp-up is shipping code.
 
-# Run tests
-[command]
+### Pick a "quick win" task
+- ≤30 min change (typo, comment, missing test, small UX nit)
+- Touches one layer only
+- Has a clear success criterion
 
-# Build
-[command]
+### First commit checklist
+- [ ] Local env runs: build + lint + tests all green from a fresh clone
+- [ ] Made the change in the right layer (per Phase 3 table)
+- [ ] Added or updated 1 test
+- [ ] Followed naming + error-handling conventions
+- [ ] Commit message matches project style (`git log --oneline`)
+- [ ] PR description follows template (check `.github/PULL_REQUEST_TEMPLATE.md`)
+- [ ] Self-reviewed with `/review:branch` before opening PR
 
-# Lint
-[command]
-```
-
-#### Environment Variables
-Required variables (see .env.example):
-- `[VAR]` - [purpose]
-- `[VAR]` - [purpose]
-
----
-
-### Testing Strategy
-- **Unit Tests**: [location and pattern]
-- **Integration Tests**: [location and pattern]
-- **E2E Tests**: [location and pattern if available]
-- **Run Tests**: `[command]`
-
----
-
-### Code Style & Conventions
-- **Code Style**: [description]
-- **Naming**: [conventions]
-- **Comments**: [when and how]
-- **Linting**: [configuration]
-```
+### Who to ask
+- Architecture / "why is it like this": {tech lead from git shortlog}
+- Domain knowledge for area X: {recent committer to that domain}
+- Infra / deploy: {ops contact from README}
 
 ### Gate
-- [ ] Architecture explained clearly
-- [ ] Key components documented
-- [ ] Workflows mapped
-- [ ] Setup instructions provided
+- [ ] Local env verified
+- [ ] First "quick win" task picked
+- [ ] First-commit checklist printed
 
 ---
 
-## Phase 4: GUIDE
-
-**Goal**: Create a practical navigation guide for common tasks
+## Final Report
 
-### Actions
-1. **Create task-based guides** (how to add features, fix bugs)
-2. **Document where to find things** (quick reference)
-3. **List common gotchas** and solutions
-4. **Provide quick wins** (easy first tasks)
-
-### Guide Template
 ```markdown
-## Navigation Guide
-
-### How to Add a New Feature
-
-Following the **[architecture pattern from doc]**, here's the step-by-step:
-
-1. **Define in Domain Layer** (if applicable):
-   - Create entity: `[path]/entities/`
-   - Create use case: `[path]/usecases/`
-
-2. **Implement in Data Layer**:
-   - Create repository: `[path]/repositories/`
-   - Create data source: `[path]/datasources/`
+## Onboarding Complete: {project}
 
-3. **Build in Presentation Layer**:
-   - Create UI component: `[path]/screens/` or `[path]/pages/`
-   - Add state management: `[path]/providers/` or `[path]/stores/`
+### Mental Model
+- Stack: {...}
+- Architecture: {...}
+- {N} domains identified
 
-4. **Add Tests**:
-   - Unit tests: `[path]/test/`
-   - Integration tests: `[path]/test/`
+### Output
+- Saved 1-page overview to {path}
+- "Where to find things" table → {path}
+- Gotchas list → {path}
 
-5. **Update Documentation**:
-   - Update README if needed
-   - Add inline documentation
-
-### How to Fix a Bug
-
-1. **Locate the Layer** (use architecture doc):
-   - UI bug? → Check Presentation layer at `[path]`
-   - Business logic bug? → Check Domain layer at `[path]`
-   - Data bug? → Check Data layer at `[path]`
-
-2. **Find Related Files**:
-   - Search by feature: `grep -r "[feature_name]" [layer_path]`
-   - Check recent changes: `git log --oneline [file]`
-
-3. **Fix Following Patterns** (from architecture doc)
-
-4. **Test**:
-   - Run existing tests: `[command]`
-   - Add regression test
-
-### Where to Find Things
-
-| What | Where |
-|------|-------|
-| API endpoints | `[path]` |
-| Database models | `[path]` |
-| UI components | `[path]` |
-| Business logic | `[path]` |
-| State management | `[path]` |
-| Constants | `[path]` |
-| Utils/Helpers | `[path]` |
-| Config | `[path]` |
-| Tests | `[path]` |
-| Types/Interfaces | `[path]` |
-
-### Common Tasks Quick Reference
-
-#### Add a new API endpoint
-```bash
-1. Define route in [path]
-2. Create controller in [path]
-3. Add service logic in [path]
-4. Update types in [path]
-5. Test with [command]
-```
-
-#### Add a new UI component
-```bash
-1. Create component in [path]
-2. Add styles in [path]
-3. Export from [path]
-4. Use in [path]
+### First Commit
+- Task: {quick-win}
+- Local env: ✅ build / ✅ lint / ✅ tests
+- PR will follow: {project PR template}
 ```
 
-#### Add a new database table/model
-```bash
-1. Create migration in [path]
-2. Define model in [path]
-3. Add repository in [path]
-4. Run migration: [command]
-```
-
-### Common Gotchas & Solutions
-
-1. **[Gotcha 1]**
-   - Problem: [description]
-   - Solution: [how to fix]
-
-2. **[Gotcha 2]**
-   - Problem: [description]
-   - Solution: [how to fix]
-
-3. **[Gotcha 3]**
-   - Problem: [description]
-   - Solution: [how to fix]
-
-### Quick Wins (Easy First Tasks)
-
-Good first issues to familiarize yourself:
-
-1. **Fix a typo or improve documentation**
-   - Files: README.md, comments
-   - Impact: Low risk, good learning
-
-2. **Add a simple utility function**
-   - Location: `[path]/utils/`
-   - Pattern: [describe pattern]
-
-3. **Add a test for existing code**
-   - Location: `[path]/test/`
-   - Framework: [test framework]
-
-4. **Improve error messages**
-   - Location: `[path]/errors/`
-   - Pattern: [describe pattern]
-
-### Git Workflow
-
-```bash
-# Create feature branch
-git checkout -b feature/[name]
-
-# Make changes following architecture
-
-# Commit (follow conventional commits)
-git commit -m "[type]: [description]"
-
-# Push and create PR
-git push origin feature/[name]
-gh pr create
-```
-
-### Getting Help
-
-- **Architecture Reference**: `~/.claude/architecture/[stack].md`
-- **Project Docs**: `docs/` or `README.md`
-- **Code Comments**: Well-documented files in `[path]`
-- **Tests as Examples**: `[path]/test/` shows usage patterns
-```
-
-### Gate
-- [ ] Task guides created
-- [ ] Navigation reference provided
-- [ ] Common gotchas documented
-- [ ] Quick wins identified
-
 ---
 
-## Quick Reference
-
-### Architecture Docs
-| Stack | Doc |
-|-------|-----|
-| All | `clean-architecture.md` |
-| Flutter | `flutter-mobile.md` |
-| React | `react-frontend.md` |
-| Go | `go-backend.md` |
-| Laravel | `laravel-backend.md` |
-| Remix | `remix-fullstack.md` |
-| Monorepo | `monorepo.md` |
-
-### Phase Summary
-| Phase | Key Actions | Output |
-|-------|-------------|--------|
-| SCAN | Identify stack, read arch doc, map structure | Project overview |
-| ANALYZE | Deep dive into layers, patterns, conventions | Architecture analysis |
-| EXPLAIN | Document components, workflows, setup | Comprehensive guide |
-| GUIDE | Create task guides, navigation, quick wins | Practical handbook |
-
-### Onboarding Checklist
-
-After completing this workflow, you should understand:
-- [ ] Project tech stack and dependencies
-- [ ] Architecture pattern and layers
-- [ ] Directory structure and where to find things
-- [ ] How to add new features (following architecture)
-- [ ] How to fix bugs (following architecture)
-- [ ] Testing strategy and how to run tests
-- [ ] Development workflow and commands
-- [ ] Common patterns and conventions
-- [ ] Where to get help
-
-### Success Criteria
-
-Onboarding is complete when you can:
-1. Explain the project architecture (based on reference doc)
-2. Locate any component or feature quickly
-3. Add a simple feature following the architecture
-4. Run tests and understand the output
-5. Navigate the codebase confidently
-
-### Next Steps After Onboarding
-
-1. **Pick a Quick Win** - Complete an easy first task
-2. **Read Architecture Doc** - Deep dive into the specific patterns
-3. **Pair with Code** - Review existing features to learn patterns
-4. **Ask Questions** - Clarify anything unclear
-5. **Start Contributing** - Begin with small features following the architecture
+## Hard Rules
+
+- **Read one module end-to-end before reading 10 partially** — the trace teaches more than skimming
+- **Capture gotchas as you find them** — they vanish from memory in days
+- **First commit ≤30 min** — bigger first changes get rabbit-holed
+- **Don't refactor on day 1** — earn context before changing conventions
 
 ---
 
@@ -591,8 +208,8 @@ Onboarding is complete when you can:
 
 | When | Use |
 |------|-----|
-| Generate full docs site after onboarding | `/docs:sync` |
-| Build first feature after onboarding | `/feature:new` |
+| Generate full doc site after onboarding | `/docs:sync` |
+| Build first real feature after onboarding | `/feature:new` |
 | First bug fix to learn the codebase | `/fix:hotfix` |
 | Author / update the onboarding doc itself | `/docs:write` |
 
@@ -600,9 +217,9 @@ Onboarding is complete when you can:
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| SCAN | `@clean-architect` | Identify architecture patterns |
-| ANALYZE | `@clean-architect` | Layer structure + boundaries |
-| ANALYZE | `@code-reviewer` | Code conventions |
+| SCAN | `@clean-architect` | Identify architecture pattern |
+| ANALYZE | `@clean-architect` | Layer + boundary analysis |
+| ANALYZE | `@code-reviewer` | Conventions + smell check |
 | ANALYZE | `@security-audit` | Security patterns |
-| EXPLAIN | `@docs-writer` | Generate explanations |
-| GUIDE | `@docs-writer` | Navigation guide |
+| EXPLAIN | `@docs-writer` | 1-page overview |
+| GUIDE | `@docs-writer` | First-commit checklist |