onboard

/onboard — Developer Onboarding Brief

Purpose

Generate a personalized onboarding brief for a new developer joining the project.

Trigger

• "Generate an onboarding guide"
• "I'm new to this project, where do I start?"
• "Create a developer onboarding brief"

Type: /onboard

---

Steps

1. Load codebase statistics from DB

const queries = require('./.claude/query-helpers.js');
const stats = queries.getCodebaseStats();

Returns:

• totalFiles, totalEdges, totalLines
• languages (array with counts)
• averageRiskScore, medianRiskScore
• graphCoverage (%)
• testedFiles (count)

2. Load MASTER.md

Read .wednesday/codebase/MASTER.md to extract:

• Product orientation (what the project does)
• Architecture overview
• Tech stack (languages + key libraries)
• Reading order (if available)

If MASTER.md doesn't exist, suggest running /brownfield-map first.

3. Identify risk files to avoid

const highRiskFiles = queries.getHighRiskFiles(minRisk = 60);

Returns files with risk score > 60, sorted by risk. These are the danger zones.

4. Find entry points with confidence

const entryPoints = queries.getHighConfidenceEntryPoints(threshold = 70);

Returns entry points sorted by confidence score. High confidence (>70%) are primary entry points.

5. Identify files by role

const filesByRole = queries.getFilesByRole();

Groups files by their classification:

• Adapters (for external dependencies)
• Logic (core business logic)
• Infra (framework/middleware)
• Entry (entry points)
• Util (utilities)

6. Identify background processes

Background processes are included in MASTER.md and marked via role classification. Adapters from step 5 show external integrations (DB, APIs, payment processors, etc.)

7. Build the onboarding brief

Format:

# Onboarding Guide — <Project Name>

Welcome! This guide will help you ramp up on this codebase.

---

## What This Project Does

[From MASTER.md — 1-2 sentences]

Example: "This is an intelligent code analysis platform that helps developers understand complex codebases through dependency graphs, risk scoring, and AI-powered summaries. Used by 50+ companies to accelerate onboarding and reduce technical debt."

---

## Tech Stack

**Languages:** <list>  
**Frameworks:** <list>  
**Databases:** <list>  
**Key libraries:** <list>  

---

## Architecture

[From MASTER.md — 2-3 sentences]

Example: "The architecture follows a layered pattern: parsers read source code, the graph engine builds dependency relationships, analyzers compute risk and impacts, and LLM enrichment adds human-readable summaries. Data flows: parse → graph → analyze → summarize → output."

---

## Where to Start Reading

Read these files in order. Each builds context for the next:

1. **<entry-file-1>** — <what it does & why it's first>
2. **<core-file-1>** — <role in architecture>
3. **<core-file-2>** — <role>
...

[8-12 ordered files from the reading order or computed via fan-in]

> **Tip:** Each file has a summary in `.wednesday/codebase/summaries.json` if you get stuck.

---

## External Dependencies

This project talks to:

**Databases:**
- PostgreSQL (user data, cache layer)
- SQLite (local graph DB)

**APIs:**
- OpenRouter (LLM enrichment)
- GitHub API (PR comments, issue triage)

**Services:**
- SonarQube (code quality analysis)

⚠️ Most require API keys. Check `.env.example` for setup.

---

## Background Processes

- **Cron jobs:** <N> scheduled tasks
  - Daily: stale dependency check
  - Weekly: skill registry update
- **Event listeners:** PR webhooks, GitHub Actions triggers
- **Async workers:** LLM summarization (can take 30s per module)

---

## Files to Never Touch Without Asking

These are high-risk. Changes here cascade widely:

- **<risk-file-1>** (risk: 78/100)
  - <Why it's risky>
  - <Who to ask before touching>
  
- **<risk-file-2>** (risk: 72/100)
  - <Why>
  - <Owner>

[Top 3-5 danger zones]

---

## First Task Recommendation

To build confidence, start here:

1. Read the entry file and understand the command flow
2. Pick a low-risk utility file and trace its usage
3. Read the architecture summary in MASTER.md
4. Run `/brownfield-map` to generate fresh analysis
5. Use `/brownfield-chat` to ask questions as you go

Once comfortable:
- Pick a small bug from issues (marked "good first issue")
- Use `/brownfield-fix` before editing
- Use `/brownfield-blast` to see your change impact
- Open a PR — we'll review and guide you

---

## Useful Commands

```bash