wiki-onboarding

What this skill does

# Wiki Onboarding Guide Generator

Generate four audience-tailored onboarding documents in an `onboarding/` folder, each giving a different stakeholder exactly the understanding they need.

## Source Repository Resolution (MUST DO FIRST)

Before generating any guides, you MUST determine the source repository context:

1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists
2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_
   - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)`
   - Local-only → use **local citations**: `(file_path:line_number)`
3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD`
4. **Do NOT proceed** until source repo context is resolved

## When to Activate

- User asks for onboarding docs or getting-started guides
- User runs `/deep-wiki:onboard` command
- User wants to help new team members understand a codebase

## Output Structure

Generate an `onboarding/` folder with these files:

```
onboarding/
├── index.md                    # Onboarding hub — links to all 4 guides with audience descriptions
├── contributor-guide.md        # For new contributors (assumes Python or JS background)
├── staff-engineer-guide.md     # For staff/principal engineers
├── executive-guide.md          # For VP/director-level engineering leaders
└── product-manager-guide.md    # For product managers and non-engineering stakeholders
```

### `index.md` — Onboarding Hub

A landing page with:
- **One-paragraph project summary**
- **Guide selector table**:

| Guide | Audience | What You'll Learn | Time |
|-------|----------|-------------------|------|
| [Contributor Guide](./contributor-guide.md) | New contributors with Python/JS experience | Setup, first PR, codebase patterns | ~30 min |
| [Staff Engineer Guide](./staff-engineer-guide.md) | Staff/principal engineers | Architecture, design decisions, system boundaries | ~45 min |
| [Executive Guide](./executive-guide.md) | VP/directors of engineering | Capabilities, risks, team topology, investment thesis | ~20 min |
| [Product Manager Guide](./product-manager-guide.md) | Product managers | Features, user journeys, constraints, data model | ~20 min |

## Language Detection

Scan the repository for build files to determine the primary language for code examples:
- `package.json` / `tsconfig.json` → TypeScript/JavaScript
- `*.csproj` / `*.sln` → C# / .NET
- `Cargo.toml` → Rust
- `pyproject.toml` / `setup.py` / `requirements.txt` → Python
- `go.mod` → Go
- `pom.xml` / `build.gradle` → Java

---

## Guide 1: Contributor Guide

**File**: `onboarding/contributor-guide.md`
**Audience**: Engineers joining the project. Assumes proficiency in Python or JavaScript and general software engineering experience.
**Length**: 1000–2500 lines. Progressive — each section builds on the last.

### Required Sections

**Part I: Foundations** (skip if repo uses Python or JS)
1. **{Primary Language} for Python/JS Engineers** — Syntax comparison tables, async model, collections, type system, package management. Concrete code side-by-side, NOT abstract descriptions.
2. **{Primary Framework} Essentials** — Compare to equivalent Python/JS frameworks (e.g., FastAPI, Express). Request pipeline, routing, DI, config.

**Part II: This Codebase**
3. **What This Project Does** — 2-3 sentence elevator pitch
4. **Project Structure** — Annotated directory tree (what lives where and why). Include `graph TB` architecture overview.
5. **Core Concepts** — Domain-specific terminology explained with code examples. Use `erDiagram` for data model.
6. **Request Lifecycle** — `sequenceDiagram` (with `autonumber`) tracing a typical request end-to-end.
7. **Key Patterns** — "If you want to add X, follow this pattern" templates with real code

**Part III: Getting Productive**
8. **Prerequisites & Setup** — Table: Tool, Version, Install Command. Step-by-step with expected output at each step.
9. **Your First Task** — End-to-end walkthrough of adding a simple feature
10. **Development Workflow** — Branch strategy, commit conventions, PR process. Use `flowchart` diagram.
11. **Running Tests** — All tests, single file, single test, coverage commands
12. **Debugging Guide** — Common issues table: Symptom, Cause, Fix
13. **Common Pitfalls** — Mistakes every new contributor makes and how to avoid them

**Appendices**
- **Glossary** (40+ terms)
- **Key File Reference** — Table: Path, Purpose, Why It Matters, Source
- **Quick Reference Card** — Cheat sheet of most-used commands and patterns

### Rules
- All code examples in the detected primary language
- Every command must be copy-pasteable with expected output
- **Minimum 5 Mermaid diagrams** (architecture, ER, sequence, flowchart, state)
- Use Mermaid for workflow diagrams (dark-mode colors) — add `<!-- Sources: ... -->` comment block after each
- Ground all claims in actual code — cite using linked format

---

## Guide 2: Staff Engineer Guide

**File**: `onboarding/staff-engineer-guide.md`
**Audience**: Staff/principal engineers who need the "why" behind every decision. Deep systems experience, may not know this repo's language.
**Length**: 800–1200 lines. Dense, opinionated, architectural.

### Required Sections

1. **Executive Summary** — What the system is in one dense paragraph. What it owns vs delegates.
2. **The Core Architectural Insight** — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo.
3. **System Architecture** — Full Mermaid `graph TB` diagram. Call out the "heart" of the system.
4. **Domain Model** — Mermaid `erDiagram` of core entities. Data invariants table: Entity, Invariant, Enforced By, Source.
5. **Key Abstractions & Interfaces** — `classDiagram` showing load-bearing abstractions.
6. **Request Lifecycle** — `sequenceDiagram` (with `autonumber`) showing typical request from entry to response.
7. **State Transitions** — `stateDiagram-v2` for entities with meaningful lifecycle states.
8. **Decision Log** — Table: Decision, Alternatives Considered, Rationale, Source.
9. **Dependency Rationale** — Table: Dependency, Purpose, What It Replaced, Source.
10. **Data Flow & State** — How data moves through the system. Storage comparison table.
11. **Failure Modes & Error Handling** — `flowchart` for error propagation paths.
12. **Performance Characteristics** — Bottlenecks, scaling limits, hot paths.
13. **Security Model** — Auth, authorization, trust boundaries, data sensitivity.
14. **Testing Strategy** — What's tested, what isn't, testing philosophy.
15. **Known Technical Debt** — Table: Issue, Risk Level, Affected Files, Source.
16. **Where to Go Deep** — Recommended reading order of source files, links to wiki sections.

### Rules
- Use **pseudocode in a different language** to explain concepts
- Use **comparison tables** to map unfamiliar concepts (e.g., `Task<T>` = `Awaitable[T]`)
- Dense prose with tables, NOT shallow bullet lists
- Every claim backed by linked citation
- **Minimum 5 Mermaid diagrams** (architecture, ER, class, sequence, state, flowchart)
- Each diagram followed by `<!-- Sources: ... -->` comment block
- **Use tables aggressively** — decisions, dependencies, debt should ALL be tables with Source columns
- Focus on WHY decisions were made, not just WHAT exists

---

## Guide 3: Executive Guide

**File**: `onboarding/executive-guide.md`
**Audience**: VP/director of engineering. Needs capability overview, risk assessment, and investment context — NOT code-level details.
**Length**: 400–800 lines. Strategic, concise, decision-oriented.

### Required Sections

1. **System Overview** — What it does, who uses it, business value in 2-3 sentences
2. **Capability Map** — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today.
3. **Architecture at a Glance** — High-level Mermaid `graph LR` dia