Onboard to Existing Codebase

Walking into a 2-year-old codebase mid-sprint with zero handoff notes is standard practice in outsourcing. The previous team is gone, the client is waiting, and the only documentation is a stale README that references a server that no longer exists. Sun Agent Kit cuts your orientation time from days to hours by reading the codebase for you and surfacing what you actually need to know.

Overview

Goal: Understand an unfamiliar codebase well enough to contribute safely within one working day
Time: 1–2 hours (vs 1–2 days manual code reading)
Agents used: scout, researcher, doc-writer
Commands: /sk:scout, /sk:docs, /sk:graphify, /sk:ask

Prerequisites

• Sun Agent Kit installed and authenticated
• Read access to the repository (clone it locally first)
• Node.js or the project’s runtime available for build verification
• A list of the first tasks you’re expected to deliver (Jira, Linear, or plain text)

Step-by-Step Workflow

Step 1: Run the Initial Scout

/sk:scout "I'm taking over this project. Give me a full orientation: tech stack, architecture, key modules, entry points, known issues in the code, and anything a new developer needs to know before touching anything."

What happens: The agent:

1. Indexes the repository — files, language breakdown, and directory structure
2. Maps architecture by identifying entry points, service modules, and external dependencies
3. Detects code health signals such as TODO/FIXME comments, modules with no test coverage, and version mismatches
4. Writes a full orientation report to plans/reports/scout-orientation.md

Step 2: Build the Knowledge Graph

/sk:graphify "map how data flows from a user placing an order to the billing module and the notification emails going out"

What happens: The agent:

1. Traces the call graph for the requested flow across controllers, services, and integrations
2. Identifies data contracts and flags any inconsistencies (e.g., mismatched field types between services)
3. Generates a Mermaid diagram and saves the full knowledge graph report to plans/reports/

Step 3: Regenerate Missing Documentation

/sk:docs "generate technical documentation for the auth module, the API endpoints, and the database schema — the existing README is outdated"

What happens: The agent:

1. Reads source files for the requested modules and migration history
2. Discovers route handlers and documents their request/response shapes
3. Writes auth flow, API endpoint, and database schema documentation
4. Verifies documented endpoints and schema against actual source files before saving

Step 4: Ask Targeted Questions About Unfamiliar Areas

/sk:ask "how does the billing retry logic work when a Stripe charge fails? What happens to the order status?"

What happens: The agent:

1. Searches the codebase for relevant files and call sites related to the question
2. Traces the execution path end-to-end, including background workers and queues
3. Synthesizes a plain-language answer with source file citations so you can drill into the code directly
4. Flags edge cases or gaps it detects while tracing the flow

Step 5: Understand the First Tasks in Context

/sk:ask "I need to fix a bug where users aren't receiving order confirmation emails. Walk me through the notification pipeline and where the failure is most likely to be."

What happens: The agent:

1. Traces the notification pipeline from the trigger event through queues and workers to the delivery integration
2. Identifies the most probable failure points based on the code
3. Returns a prioritized list of locations to investigate, with source line references

Complete Example: You Join a 2-Year-Old Node.js Project Mid-Sprint

Scenario: It’s Monday. A client’s long-term vendor just offboarded. Your team takes over a Node.js/React e-commerce project. There’s a 3-ticket sprint in progress, a QA regression in the cart module, and the client expects a standup Wednesday. You have zero context.

Monday morning — 2 hours to get oriented:

# Full orientation pass — read this report before anything else
/sk:scout "complete orientation for a new engineer taking over this project mid-sprint. Tech stack, architecture, critical modules, test coverage gaps, and any time bombs in the code."

# Map the cart module specifically — that's where the regression is
/sk:graphify "trace the full data flow through the cart module: add to cart, update quantity, apply coupon, checkout handoff"

# Regenerate docs that are clearly out of date
/sk:docs "update README with current stack and setup steps, and generate API docs for the cart and checkout routes"

# Answer the most pressing question
/sk:ask "there's a regression in cart — coupon codes that previously worked are now returning 400. What changed in the cart or coupon service recently and where should I look first?"

Result: By noon Monday you have a detailed orientation report, a data-flow diagram of the cart module, refreshed docs, and a probable root cause for the regression (a schema change renamed a column but the validation middleware wasn’t updated). You walk into Wednesday’s standup having already submitted a fix.

Time Comparison

Best Practices

1. Run scout before touching any code ✅

Scout gives you the lay of the land. Modifying code before you understand the architecture is how subtle regressions get introduced. Always orient first.

2. Use /sk:graphify for specific flows, not the entire codebase ✅

Asking for “the entire data flow of the application” produces an overwhelming graph. Scope it to a domain: “trace the checkout flow from cart submission to payment confirmation.”

3. Ask targeted questions with /sk:ask rather than reading files manually ✅

Instead of opening 12 files to understand how retries work, ask in plain language. The agent cites source lines so you can drill into the code when needed.

4. Skipping scout to “just dive in” ❌

Diving straight into tickets without orientation leads to duplicate logic, broken assumptions about data contracts, and bugs that take days to trace. The time scout takes will save you hours.

5. Trusting generated docs without verifying one key flow manually ❌

Generated docs are accurate but not infallible. Pick the single most critical flow in your first sprint and trace it manually to validate the docs. Once you trust one flow, you can trust the rest.

Troubleshooting

Problem: Scout report is very long and hard to navigate

Solution: Ask for a focused sub-report: /sk:scout "focus only on the auth module and the API layer, skip the frontend". You can run multiple targeted scouts rather than one massive one.

Problem: /sk:graphify produces an empty or incomplete diagram

Solution: The trace depends on readable import paths. If the project uses path aliases (like @/services/billing) that aren’t resolved in tsconfig, run /sk:ask "list all path aliases in tsconfig and their resolved paths" first.

Problem: /sk:ask gives confident but wrong answers

Solution: Always check the source line citations in the answer output. If the answer seems off, run /sk:scout "re-analyze src/services/billing.ts specifically" for a fresh, file-focused read.

Problem: Generated documentation doesn’t match the actual database schema

Solution: The schema doc generation reads migration files. If migrations were applied out of order or some were skipped in the local environment, there will be drift. Run /sk:ask "list all migration files and their applied status" to surface inconsistencies.

Next Steps

• Fix Bugs Systematically — your first task after onboarding is often a regression or bug fix
• Add a New Feature — once you understand the codebase, add to it confidently
• Start a New Project — for when you’re building greenfield instead of inheriting brownfield

Key takeaway: You should never spend more than a morning reading someone else’s code cold — /sk:scout and /sk:graphify turn two days of painful code archaeology into a two-hour structured orientation.