docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: 'step-01-define-question'
|
||||
description: 'Articulate exactly what you need to understand about the codebase before reading a single file'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-02-scan-codebase.md'
|
||||
---
|
||||
|
||||
# Step 1: Define Question
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Articulate exactly what you need to understand about the codebase before reading a single file.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on defining clear analysis questions, scope, expected output, and time box
|
||||
- 🚫 FORBIDDEN to begin scanning or reading any codebase files — that is a later step
|
||||
- 💬 Approach: Help user articulate their question clearly and set boundaries before any exploration
|
||||
- 📋 If user provides vague questions, help them sharpen and prioritize
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a clear, scoped analysis question with defined boundaries
|
||||
- 💾 Save the question, scope, output format, and time box for subsequent steps
|
||||
- 📖 Reference the category table and scope options to guide user
|
||||
- 🚫 Do not open, scan, or explore any code during this step
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: User's initial request or motivation for analysis
|
||||
- Focus: Defining what to analyze and how to scope it
|
||||
- Limits: No codebase exploration yet — purely planning
|
||||
- Dependencies: None — this is the first step
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Articulate the Question
|
||||
|
||||
Write down what you need to understand. Common analysis questions:
|
||||
|
||||
| Category | Example Questions |
|
||||
|----------|-------------------|
|
||||
| **Architecture** | How is this application structured? What patterns does it use? |
|
||||
| **Dependencies** | What does this module depend on? What would break if I change it? |
|
||||
| **Patterns** | What conventions does the team follow? Where are they inconsistent? |
|
||||
| **Performance** | Where are the bottlenecks? What queries are expensive? |
|
||||
| **Data flow** | How does data move from user input to database and back? |
|
||||
| **Integration** | What external services does this connect to? How? |
|
||||
| **Security** | Where is authentication handled? Are there exposed endpoints? |
|
||||
|
||||
Write the question in plain language. If you have multiple questions, prioritize them.
|
||||
|
||||
### 2. Define Scope
|
||||
|
||||
Determine what is in and out of scope:
|
||||
|
||||
- **Entire codebase** — Full architecture review (use for onboarding or documentation)
|
||||
- **Specific module** — One feature area, service, or package
|
||||
- **Cross-cutting concern** — Authentication, error handling, logging across the codebase
|
||||
- **Integration boundary** — How two systems communicate
|
||||
|
||||
Be explicit about what you will NOT analyze. Unbounded scope leads to analysis paralysis.
|
||||
|
||||
### 3. Define Expected Output
|
||||
|
||||
Decide what the analysis should produce:
|
||||
|
||||
- **Architecture map** — High-level component diagram with relationships
|
||||
- **Dependency graph** — Module dependencies, import chains
|
||||
- **Pattern catalog** — Design patterns used, where, and how consistently
|
||||
- **API map** — Endpoints, request/response shapes, authentication
|
||||
- **Data model** — Entity relationships, storage patterns
|
||||
- **Risk assessment** — Tech debt, security concerns, fragile areas
|
||||
|
||||
### 4. Set Time Box
|
||||
|
||||
Decide how long the analysis should take. Recommended:
|
||||
|
||||
| Scope | Time Box |
|
||||
|-------|----------|
|
||||
| Single module | 15-30 min |
|
||||
| Feature area | 30-60 min |
|
||||
| Full codebase | 1-2 hours |
|
||||
|
||||
If the time box expires, document what you found and what remains unexplored.
|
||||
|
||||
### 5. Verify Checklist
|
||||
|
||||
- [ ] Question is written in plain language
|
||||
- [ ] Scope boundaries are defined (what is in, what is out)
|
||||
- [ ] Expected output format is chosen
|
||||
- [ ] Time box is set
|
||||
|
||||
### 6. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 2: Scan Codebase"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the user has confirmed a clear question, scope, output format, and time box will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Question is written in plain language
|
||||
- Scope boundaries are defined (what is in, what is out)
|
||||
- Expected output format is chosen
|
||||
- Time box is set
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Beginning codebase exploration before question is defined
|
||||
- Proceeding without clear scope boundaries
|
||||
- Skipping time box definition
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
Reference in New Issue
Block a user