cc-new-session-onboard.md

Okay Claude, let's initiate your deep dive into this codebase. This project may be large or complex, so your ability to perform effective in-context learning on the fly is crucial. Treat this as an investigative process where you leverage your strengths in code analysis, pattern recognition, and knowledge synthesis.

Your Objective: Build a robust, foundational understanding ('mental model' or 'knowledge graph') of this system's architecture, core workflows, data flow, and key components/modules. This understanding should be deep enough to allow you to confidently and accurately tackle diverse development, analysis, or refactoring tasks I'll give you later.

Your Strategy - The 'Explore, Synthesize, Verify' Loop:

1. Explore (Breadth-First): Start by getting the lay of the land.

   • Examine the primary entry points (e.g., main functions, API definitions, main application/server scripts, UI bootstrap files).
   • Thoroughly check any high-level documentation provided. If a _project_context folder exists and you've been instructed to use it, start there. Look for top-level READMEs, CONTRIBUTING guides, architecture diagrams, or design documents.
   • Use your tools (Read, Glob, Grep, etc.) to identify the major modules, directories (e.g., src, lib, app, components, services, utils, core, api, db), and the main actors or data entities within the codebase. Get a sense of the project's overall structure. Check git history for understanding of progression.

2. Synthesize (Build the Model): As you gather information, actively construct your understanding. Don't just read; connect the dots. Think step-by-step or outline the flow:

   • How does a typical request, task, or unit of data enter the system and move through its various stages or components?
   • What are the distinct responsibilities and characteristics of the major modules/components you've identified? How do they appear to relate to each other?
   • What architectural patterns or common design principles seem to be evident (e.g., MVC, microservices, event-driven, layered architecture, specific data access patterns, error handling strategies, state management approaches)?
   • Formulate initial hypotheses about how different parts of the system interact and their dependencies.

3. Verify & Refine (Depth-First on Core Paths): Now, validate your emerging model. Dive deeper into the code paths that seem most critical to the system's core functionality or purpose. This might involve:

   • Tracing the execution flow of a primary use case (e.g., handling a key API request, processing a core data transformation, rendering a main UI component).
   • Examining how core business logic is implemented and where key decisions are made.
   • Understanding how important data structures are defined, managed, and persisted (if applicable).
   • Does the actual code (specific functions, classes, data structures, control flow) align with your synthesized understanding and any available documentation?
   • If there are discrepancies or surprises, refine your mental model. Note down these refinements and any new questions that arise.
   • If helpful, use git log or similar tools on key files/modules to understand their evolution or the rationale behind certain design choices.

Key Areas to Prioritize for Foundational Understanding:

• The end-to-end lifecycle of the system's primary task(s), request(s), or data flow(s).
• The fundamental roles, responsibilities, and interactions of the most significant modules/components you identify.
• The system's approach to data management (e.g., how data is structured, stored, retrieved, and manipulated; database schemas if present; important data models or state management techniques).
• The primary mechanisms for inter-component or inter-module communication (e.g., direct function calls, APIs, event buses, message queues, shared state, etc.).
• Common utilities, libraries, or frameworks heavily used throughout the project and their purpose.

Deliverable for this Onboarding Task:

Before we move to a specific task, please provide a structured summary of your synthesized understanding based on this initial investigation. This summary should cover: a) A concise overview of the system's apparent purpose and high-level architecture as you understand it. b) A description of the core workflow(s) or data processing pipeline(s) within the system. c) Identification of what you believe are the key modules/components and their primary roles/responsibilities. d) A list of any significant assumptions you've made during this process or any major areas where your understanding is still tentative or requires further clarification. Include any questions you have.

Think of this as building your internal map of this new territory. Let me know when you have completed this initial exploration and synthesis phase and are ready to share your map. I'm here to clarify if you encounter ambiguities.