Generates two complementary onboarding guides — a Principal-Level architectural deep-dive and a Zero-to-Hero contributor walkthrough. Use when the user wants onboarding documentation for a codebase.
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:
Check for git remote: Run git remote get-url origin to detect if a remote exists
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)
Determine default branch: Run git rev-parse --abbrev-ref HEAD
until source repo context is resolved
Do NOT proceed
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
File: onboarding/contributor-guide.mdAudience: 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)
{Primary Language} for Python/JS Engineers — Syntax comparison tables, async model, collections, type system, package management. Concrete code side-by-side, NOT abstract descriptions.
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
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.mdAudience: 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
Executive Summary — What the system is in one dense paragraph. What it owns vs delegates.
The Core Architectural Insight — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo.
System Architecture — Full Mermaid graph TB diagram. Call out the "heart" of the system.
Domain Model — Mermaid erDiagram of core entities. Data invariants table: Entity, Invariant, Enforced By, Source.
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.mdAudience: 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
System Overview — What it does, who uses it, business value in 2-3 sentences
Capability Map — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today.
Architecture at a Glance — High-level Mermaid graph LR diagram. Services, data stores, external integrations — NO internal code details. Focus on deployment units and team boundaries.
Team Topology — Which team/person owns which components. Table: Component, Owner, Criticality, Bus Factor.
Technology Investment Thesis — Why these technologies were chosen. Table: Technology, Purpose, Alternatives Considered, Risk Level.
Tables for every structured finding — this audience reads tables, not prose
Business language — translate technical concepts into impact (reliability, velocity, cost, risk)
Guide 4: Product Manager Guide
File: onboarding/product-manager-guide.mdAudience: Product managers and non-engineering stakeholders. Needs to understand what the system does, what's possible, and where the boundaries are — NOT how it's built.
Length: 400–800 lines. User-centric, feature-focused, constraint-aware.
Required Sections
What This System Does — 2-3 sentence elevator pitch in user-facing language (no jargon)
User Journey Map — Mermaid graph LR or journey diagram showing primary user flows through the system
Feature Capability Map — Table: Feature, Status (Live/Beta/Planned/Not Possible), User-Facing Behavior, Limitations. Comprehensive map of what's built and what's not.
Data Model (Product View) — Simplified Mermaid erDiagram showing entities users interact with. Explain in business terms (e.g., "A Project has many Documents" not "FK relationship").
Configuration & Feature Flags — Table: Flag/Config, What It Controls, Default, Who Can Change It. What can be toggled without engineering work.
API Capabilities — What integrations are possible. Table: Capability, Endpoint/Method, Authentication, Rate Limits. Written for integration partners, not developers.
Known Limitations & Constraints — Honest list of what the system can't do or does poorly. Table: Limitation, User Impact, Workaround, Planned Fix.
Data & Privacy — What data is collected, where it's stored, retention policies, compliance status. Table: Data Type, Storage Location, Retention, Compliance.
Glossary — Domain terms explained in plain language (not engineering jargon)
FAQ — 10+ common questions a PM would ask, answered concisely
Rules
ZERO engineering jargon — no "middleware", "dependency injection", "ORM". Use plain language.
User-centric framing — describe everything in terms of what users experience, not how code works
Tables for every structured finding — PMs scan tables, not prose
If a technical concept must be mentioned, explain it in one sentence (e.g., "Feature flags — toggles that let us turn features on/off without deploying code")
Every claim grounded in evidence — cite wiki sections or source files for verification
