git:20261001.8adea49 to git:20261001.cc31a37

- # BosskuAI Codebase Analysis

-

- Use this skill to explain how existing code runs, trace behavior, or locate module ownership before making changes.

-

- ## How this differs from nearby skills

-

- - **`bosskuai-project-understanding`**: answers *what the project is for*, who uses it, stack, docs, and where truth lives — enough context to choose the next skills. **This skill** answers *how the code actually runs*: entry points, call chains, module boundaries, side effects, and extension points. Use project-understanding first when purpose is unclear; use codebase-analysis when you must trace behavior or map structure accurately.

- - **`bosskuai-software-architecture`**: evaluates and redesigns architectural decisions; this skill reads and maps what currently exists without passing judgment.

- - **`bosskuai-diagnose-loop`**: locates defects in a traced execution path; load this skill first to understand the path, then load diagnose-loop to locate defects within it.

- - **`bosskuai-code-revamp`**: proposes structural changes; this skill is the prerequisite read before any revamp proposal.

-

- ## Mindset

-

- - Read before you conclude. The codebase is the source of truth — not the README, not your assumptions, not the last conversation.

- - Distinguish confirmed facts (seen in code) from inferences (likely true based on patterns).

- - Generated code, compiled output, and support files are not the source of truth — find the originating source.

- - The goal is a mental model of the system that is accurate enough to make correct predictions about behavior.

-

- ## Scope and evidence

-

- - Resolve the actual project root and the behavior being investigated. Record the analyzed revision or working-tree state when available; distinguish uncommitted source from a pinned commit. Non-Git workspaces need source paths and a stated scope, not an origin remote.

- - Start with the relevant entry point and expand only when a dependency, side effect, or uncertainty requires it. State what was sampled and what remains unread.

- - Support each important runtime relationship with `file:line` evidence for the call, registration, dispatch, query, or transport. File proximity, names, or an import alone do not establish execution order or runtime causality.

- - Keep source inspection, test results, and observed runtime behavior separate. A valid source location or rendered diagram proves neither that the relationship executes nor that the behavior is correct. Re-check cited locations after edits before reusing an earlier map.

-

- ## Workflow

-

- ### Phase 1 — Orient

-

- With an available `graft/` index and CLI, use `graft callers` or `map` first (see the `graft` skill). Otherwise use narrow source searches; analysis does not require installing a graph runtime.

-

- 1. Identify the **entry points**: HTTP server, CLI entrypoint, main function, event listener, cron schedule.

- 2. Read the top-level structure: directory organization, major modules/packages, config files, test structure.

- 3. Identify the **stack**: language, runtime, framework, major dependencies, build system.

- 4. Distinguish source files from generated, compiled, or vendor files.

-

- ### Phase 2 — Trace execution paths

-

- 5. For the behavior in question, trace the **real execution path**:

- - Entry → Authentication/Authorization middleware → Routing → Handler → Business logic → Data access → Response/Side effects

- 6. At each step: what data flows in? what transforms happen? what can go wrong?

- 7. Identify **side effects** that are not immediately obvious: cache writes, event emissions, external calls, background jobs triggered.

- Label the relevant direction, action/protocol, synchronous or asynchronous transport, and failure/retry path when the source establishes them.

-

- ### Phase 3 — Map the architecture

-

- 8. Identify the **architectural style**: monolith, layered, hexagonal, microservices, event-driven, serverless, BFF, etc.

- 9. Map the **module/package boundaries**: what does each major module own? where are the boundaries?

- 10. Identify **data ownership**: which module is the source of truth for each domain entity?

- 11. Identify **integration points**: external APIs, message queues, databases, cache, third-party SDKs.

-

- ### Phase 4 — Identify quality signals

-

- 12. Scan for **tech debt markers**:

- - TODOs/FIXMEs in critical paths

- - Commented-out code blocks

- - Duplicate business logic in multiple modules

- - Deep nesting (4+ levels)

- - Functions over 100 lines

- - Missing error handling in critical paths

- - Missing or absent tests in core modules

-

- 13. Scan for **dead code signals**:

- - Exported functions/classes with no internal callers

- - Feature flags that are always true or always false

- - Unreachable branches

- - Deprecated modules still imported

-

- ### Phase 5 — Identify extension points

-

- 14. Where does the codebase expect changes to be made? (plugin pattern, strategy pattern, config-driven behavior)

- 15. What are the **safest places to add new behavior** without touching existing logic?

- 16. What are the **highest-risk areas** where changes are likely to cause regressions?

-

- ### Phase 6 — Summarize

-

- 17. State clearly what is **confirmed** (directly seen in code) vs **inferred** (pattern-based).

- 18. List open uncertainties and what would need to be read or tested to resolve them.

-

- ## Guardrails

-

- - Do not make claims about code behavior without reading the actual source — README and docs are aspirational.

- - Do not treat generated, compiled, or vendor files as the source of truth.

- - Distinguish confirmed facts (directly seen in code) from inferences (pattern-based) in every output.

- - Treat quality markers and missing internal callers as candidates, not proven defects or dead code; check public APIs, plugins, registration, and dynamic callers before recommending removal.

-

- ## Output format

-

- ```

- Analysis scope: [project root, behavior, revision / working-tree state, sampled and unread areas]

-

- Stack and entry points:

- Language / runtime: [stack]

- Frameworks: [list]

- Entry points: [list with file paths]

- Build / test system: [tools]

-

- Architecture:

- Style: [monolith / layered / hexagonal / microservices / etc.]

- Major modules: [module — what it owns — key files]

- Data ownership: [entity — owning module]

- Integration points: [external systems — how connected]

-

- Execution path (for [behavior]):

- [entry] → [middleware] → [handler] → [logic] → [data access] → [response / side effects]

- Side effects not immediately obvious: [list]

-

- Code quality signals:

- Tech debt markers: [location — issue]

- Dead code candidates: [location — signal]

- Strong patterns: [what the codebase does well]

- Weak patterns: [what needs attention]

-

- Extension points:

- Safest places to add behavior: [list]

- High-risk areas (change carefully): [list]

-

- Confirmed vs inferred:

- Confirmed: [facts seen directly in code with source locations]

- Inferred: [reasonable assumptions from patterns]

- Exercised: [behavior actually checked, command and result, or not run]

- Open uncertainties:

- [question — what would resolve it]

- ```

- ## References

- - `../../references/checklists/codebase-analysis-checklist.md`

- - `../../references/pitfalls/performance-pitfalls.md` (hot paths, N+1, unbounded reads while tracing)