From 4a37cc1c1e4cab66ab7b8d295646e3edf9a0c128 Mon Sep 17 00:00:00 2001 From: Nikita Levyankov Date: Thu, 12 Feb 2026 12:57:50 +0200 Subject: [PATCH] feat(skills): implement tech-lead skill for structured task implementation Add comprehensive tech-lead skill that provides structured guidance for implementing features and tasks: - Requirement gathering from Jira tickets (via brianna) or user descriptions - 5-phase workflow: gathering, analysis, complexity assessment, recommendation, implementation - Complexity rating system (Simple/Medium/Complex) with evidence-based reasoning - Integration with solution-architect skill for complex features - Branch creation and naming conventions (Jira: EPMCDME-XXXXX, non-Jira: feature/name) - Layer-by-layer implementation guidance following project architecture - Reference documentation and example workflows Resolves EPMCDME-10387 Generated with AI Co-Authored-By: codemie-ai --- .claude/skills/tech-lead/SKILL.md | 433 +++++++++++++++ .../examples/complex-feature-example.md | 330 ++++++++++++ .../examples/non-jira-task-example.md | 442 ++++++++++++++++ .../examples/simple-feature-example.md | 181 +++++++ .../tech-lead/references/branch-workflow.md | 499 ++++++++++++++++++ .../references/complexity-assessment-guide.md | 415 +++++++++++++++ 6 files changed, 2300 insertions(+) create mode 100644 .claude/skills/tech-lead/SKILL.md create mode 100644 .claude/skills/tech-lead/examples/complex-feature-example.md create mode 100644 .claude/skills/tech-lead/examples/non-jira-task-example.md create mode 100644 .claude/skills/tech-lead/examples/simple-feature-example.md create mode 100644 .claude/skills/tech-lead/references/branch-workflow.md create mode 100644 .claude/skills/tech-lead/references/complexity-assessment-guide.md diff --git a/.claude/skills/tech-lead/SKILL.md b/.claude/skills/tech-lead/SKILL.md new file mode 100644 index 0000000..826ebb4 --- /dev/null +++ b/.claude/skills/tech-lead/SKILL.md @@ -0,0 +1,433 @@ +--- +name: tech-lead +description: This skill should be used when the user asks to "implement a Jira ticket", "start working on EPMCDME ticket", "analyze task", "begin implementation", "implement new task", "implement feature", "act as tech lead", "plan implementation", "how should I implement", or wants structured technical leadership for implementing features. Acts as a technical lead to guide implementation from requirements (Jira ticket or user description) through complexity assessment, architectural analysis, branch creation, and pattern-driven coding. +version: 0.1.0 +--- + +# Tech Lead: Structured Implementation Guide + +## Purpose + +This skill acts as a technical lead to guide implementation of features and tasks with a structured approach. It bridges the gap between requirements and code by: +- Gathering requirements (from Jira tickets or user descriptions) +- Analyzing codebase and architectural patterns +- Assessing complexity and risks +- Creating feature branches +- Driving implementation with proper guidance + +The skill ensures structured, informed development that follows project patterns and architectural guidelines. + +## When to Use This Skill + +Use this skill when: +- Starting work on a Jira ticket (EPMCDME-XXXX) +- Implementing a new feature or task (with or without Jira ticket) +- Need to assess implementation complexity before coding +- Want guidance on where and how to implement changes +- Need to create a proper feature branch +- Transitioning from requirements to implementation + +## Implementation Workflow + +### Phase 1: Requirement Gathering + +**Step 1: Determine Requirement Source** + +Check if user provided: +- **Jira ticket ID** (EPMCDME-XXXXX format) +- **Task description** (user-provided text) + +**Step 1a: If Jira Ticket Provided** + +Use the brianna skill to fetch ONLY description and summary fields: + +``` +Use Skill tool with skill="brianna" and args containing: +- Action: get ticket details +- Ticket ID: [provided by user] +- Fields: description, summary ONLY +``` + +Do NOT request other fields like status, assignee, or custom fields unless explicitly needed for complexity assessment. + +**Step 1b: If Task Description Provided** + +If user provides a task description without a Jira ticket: + +1. **Confirm understanding** of the requirements +2. **Ask clarifying questions** if requirements are vague +3. **Document requirements** in a structured format for later reference + +Example: +```markdown +## Task Requirements + +**Goal**: [What needs to be implemented] + +**Acceptance Criteria**: +- [Criterion 1] +- [Criterion 2] +- [Criterion 3] + +**Context**: [Any additional context or constraints] +``` + +**Step 2: Branch Naming Decision** + +Determine appropriate branch name: + +**If Jira ticket exists:** +- Branch name: `EPMCDME-XXXXX` (exact ticket ID) + +**If no Jira ticket:** +- Ask user for preferred branch name +- Suggest format: `feature/descriptive-name` or `task/descriptive-name` +- Example: `feature/add-user-logging`, `task/improve-error-handling` + +### Phase 2: Technical Analysis + +**Step 3: Explore Codebase and Guides** + +After obtaining ticket details, perform targeted exploration: + +1. **Check Relevant Guides First (MANDATORY)** + - Identify task category from ticket (API, Agent, Database, etc.) + - Use Read tool to load P0 guides from `.codemie/guides/` + - Reference CLAUDE.md Task Classifier for guide mapping + +2. **Search Codebase** + - Use Grep to find related code patterns + - Use Glob to locate relevant files + - Identify existing implementations to follow + +3. **Understand Architecture** + - Determine affected layers (API → Service → Repository) + - Identify integration points + - Check for similar existing features + +**Exploration Guidelines:** +- Focus on code patterns mentioned in ticket +- Prioritize guides over blind codebase search +- Look for existing similar implementations +- Identify affected components and dependencies + +**Step 4: Clarifying Questions (Selective)** + +Ask clarifying questions ONLY when: +- Requirements are ambiguous or contradictory +- Multiple valid implementation approaches exist +- Architectural decisions need user input +- Ticket lacks critical technical details + +**Do NOT ask about:** +- Information already present in code +- Generic questions ("Should I use async?") +- Standard patterns covered in guides +- Details that can be inferred from existing implementations + +Use AskUserQuestion tool with focused, specific questions that unblock implementation decisions. + +### Phase 3: Complexity Assessment + +**Step 5: Analyze and Report Complexity** + +Provide a structured complexity assessment in this format: + +```markdown +## Implementation Analysis: [TICKET-ID] + +### Complexity Rating: [Simple | Medium | Complex] + +### Reasoning: +- **[Point 1]**: [Explanation of complexity factor] +- **[Point 2]**: [Explanation of complexity factor] +- **[Point 3]**: [Explanation of complexity factor] +- **[Point 4]**: [Explanation of complexity factor - optional] + +### Clarity Assessment: +[Clear | Partially Clear | Unclear] - [Brief explanation] + +### Affected Components: +- **[Component 1]**: [File path or module] - [Nature of change] +- **[Component 2]**: [File path or module] - [Nature of change] +- **[Component 3]**: [File path or module] - [Nature of change] +``` + +**Complexity Criteria:** + +**Simple:** +- Single component affected +- Well-defined requirements +- Existing patterns to follow +- No architectural decisions needed +- Estimated 1-3 files to change + +**Medium:** +- 2-3 components affected +- Clear requirements with minor gaps +- May require some architectural decisions +- Estimated 4-8 files to change +- Requires coordination between layers + +**Complex:** +- 4+ components affected +- Ambiguous or incomplete requirements +- Significant architectural decisions needed +- Estimated 9+ files to change +- Cross-cutting concerns (security, performance) +- New integrations or external dependencies + +### Phase 4: Recommendation + +**Step 6: Provide Implementation Recommendation** + +Based on complexity assessment, provide one of these recommendations: + +**For Simple/Medium Complexity:** +```markdown +### Recommendation + +This feature is [Simple/Medium] complexity and can be implemented directly. + +**Suggested Approach:** +1. Create feature branch: `[branch-name]` +2. [Step-by-step implementation guidance] +3. [Key patterns to follow] +4. [Testing approach] + +Upon user confirmation, create the feature branch and begin implementation. +``` + +**For Complex Complexity:** +```markdown +### Recommendation + +This feature is Complex and would benefit from architectural planning. + +**Suggested Next Steps:** +1. Use solution-architect skill to create detailed specification +2. Address architectural decisions: [list key decisions] +3. Define interfaces and contracts +4. Create implementation plan with milestones + +Alternatively, proceed with implementation if user accepts the complexity. Ask user to choose approach. +``` + +### Phase 5: Implementation Start + +**Step 7: Branch Creation and Implementation** + +If user agrees to proceed with implementation: + +**CRITICAL: Always create feature branch before any code changes** + +1. **Create Feature Branch:** + ```bash + # Check current branch + git branch --show-current + + # Create and switch to feature branch + # For Jira tickets: + git checkout -b EPMCDME-XXXXX + + # For non-Jira tasks (use determined branch name): + git checkout -b feature/branch-name + ``` + +2. **Verify Branch:** + ```bash + # Confirm on new branch + git branch --show-current + ``` + +3. **Begin Implementation:** + - Follow patterns identified in analysis phase + - Reference guides for standard approaches + - Implement changes layer by layer (API → Service → Repository) + - Apply security and performance patterns + +**Branch Naming:** + +For Jira tickets: +- Format: `EPMCDME-XXXXX` (exactly as ticket ID) +- No prefixes like `feature/` or `fix/` +- Use ticket number as-is + +For non-Jira tasks: +- Format: `feature/descriptive-name` or `task/descriptive-name` +- Use kebab-case for names +- Keep names concise but descriptive +- Examples: `feature/add-logging`, `task/refactor-auth` + +**Implementation Guidelines:** +- Start with repository layer (data access) +- Then service layer (business logic) +- Then API layer (endpoints) +- Test incrementally +- Follow project patterns in guides + +## Key Principles + +### Do's +✅ Always check guides before searching codebase +✅ Accept both Jira tickets and task descriptions +✅ Fetch only required Jira fields (description, summary) when applicable +✅ Provide evidence-based complexity assessment +✅ Create feature branch BEFORE any changes +✅ Follow established patterns from guides +✅ Ask specific, blocking questions only +✅ Provide clear, actionable recommendations +✅ Adapt branch naming to context (Jira vs non-Jira) + +### Don'ts +❌ Don't skip guide consultation +❌ Don't ask generic clarifying questions +❌ Don't start coding without branch creation +❌ Don't make architectural decisions for complex features without user input +❌ Don't fetch unnecessary Jira fields (when using Jira) +❌ Don't guess at complexity—analyze systematically +❌ Don't assume every task has a Jira ticket + +## Example Workflow + +### Example 1: Simple Feature (Jira Ticket) + +``` +User: "Implement EPMCDME-10500" + +Tech Lead: +1. Identifies Jira ticket format +2. Fetches ticket via brianna (description + summary) +3. Reads .codemie/guides/api/rest-api-patterns.md +4. Searches for similar endpoints with Grep +5. Assesses: Simple (1 endpoint, standard CRUD, existing pattern) +6. Recommends: Direct implementation +7. Creates branch: EPMCDME-10500 +8. Implements following REST API patterns +``` + +### Example 1b: Simple Feature (No Jira Ticket) + +``` +User: "Add logging to the authentication endpoint" + +Tech Lead: +1. Identifies task description (no Jira ticket) +2. Documents requirements in structured format +3. Asks user for branch name preference +4. Reads .codemie/guides/development/logging-patterns.md +5. Searches for auth endpoint with Grep +6. Assesses: Simple (1 file, standard pattern, clear requirements) +7. Recommends: Direct implementation +8. Creates branch: feature/add-auth-logging +9. Implements following logging patterns +``` + +### Example 2: Medium Feature (Jira Ticket) + +``` +User: "Start work on EPMCDME-10600" + +Tech Lead: +1. Fetches ticket via brianna +2. Reads guides: agents/langchain-agent-patterns.md, integration/llm-providers.md +3. Searches codebase for similar agents +4. Asks: "Should the new agent use streaming or batch mode?" +5. Assesses: Medium (new agent + tool, 5 files, clear patterns) +6. Recommends: Direct implementation with guidance +7. Creates branch: EPMCDME-10600 +8. Implements agent following LangChain patterns +``` + +### Example 3: Complex Feature + +``` +User: "Implement EPMCDME-10700" + +Tech Lead: +1. Fetches ticket via brianna +2. Reads multiple guides (architecture, workflows, integrations) +3. Identifies: 12+ files affected, new external service integration +4. Asks: "Which cloud provider should be used?" "What's the data retention policy?" +5. Assesses: Complex (multi-layer, new integration, security concerns) +6. Recommends: Use solution-architect skill first +7. If user insists: Creates branch and starts with high-level plan +``` + +## Integration with Other Skills + +### Brianna Skill +- Use for Jira ticket retrieval (when Jira ticket is provided) +- Request ONLY description and summary fields +- Handle ticket not found gracefully +- Skip if user provides task description without Jira ticket + +### Solution Architect Skill +- Invoke for Complex features needing specs +- Pass task details (Jira or user-provided) and analysis findings +- Wait for specification before implementation + +### Codemie-Commit Skill +- Use after implementation completion +- Ensure commit message references Jira ticket (if applicable) +- Follow git workflow from guides + +## Error Handling + +### Ticket Not Found +```markdown +Unable to fetch Jira ticket [ID]. Please verify: +- Ticket ID format is correct (EPMCDME-XXXXX) +- Ticket exists in Jira +- You have access to view this ticket +``` + +### Branch Already Exists +```markdown +Branch [EPMCDME-XXXXX] already exists. + +Options: +1. Switch to existing branch: `git checkout EPMCDME-XXXXX` +2. Delete and recreate: `git branch -D EPMCDME-XXXXX && git checkout -b EPMCDME-XXXXX` +3. Use different branch name (not recommended) + +Which option do you prefer? +``` + +### Guides Not Found +```markdown +Warning: Unable to locate relevant guides for this task. + +Proceeding with codebase exploration only. This may result in patterns inconsistent with project standards. + +Continue? Consider updating guide paths if this persists. +``` + +## Success Criteria + +A successful tech-lead session results in: +- ✅ Jira ticket details retrieved and understood +- ✅ Relevant guides consulted +- ✅ Codebase patterns identified +- ✅ Complexity accurately assessed +- ✅ Clear recommendation provided +- ✅ Feature branch created with correct name +- ✅ Implementation started following project patterns +- ✅ User has clarity on next steps + +## Additional Resources + +### Reference Files + +For detailed patterns referenced during analysis: +- **`references/complexity-assessment-guide.md`** - Detailed complexity criteria and examples +- **`references/branch-workflow.md`** - Git branching best practices for Jira tickets + +### Integration Points + +This skill coordinates with: +- **CLAUDE.md**: Uses Task Classifier and guide references +- **`.codemie/guides/`**: Consults all relevant guides based on task type +- **brianna skill**: Fetches Jira ticket information +- **solution-architect skill**: Escalates complex features for specification +- **codemie-commit skill**: Completes implementation with proper commits diff --git a/.claude/skills/tech-lead/examples/complex-feature-example.md b/.claude/skills/tech-lead/examples/complex-feature-example.md new file mode 100644 index 0000000..57677f0 --- /dev/null +++ b/.claude/skills/tech-lead/examples/complex-feature-example.md @@ -0,0 +1,330 @@ +# Example: Complex Feature Implementation + +## Scenario + +User wants to implement: "Integrate with external document analysis service" + +Jira Ticket: EPMCDME-10750 + +**Ticket Description:** +``` +As a user, I want to analyze external documents (PDFs, Word docs) using +a third-party AI service so that I can extract insights without manual review. + +Acceptance Criteria: +- Support PDF and DOCX uploads +- Integrate with external AI service API +- Store analysis results +- Handle rate limits and errors +- Secure credential management +``` + +## Tech Lead Workflow + +### Phase 1: Requirement Gathering + +**Tech Lead:** +``` +To begin, provide the Jira ticket ID (e.g., EPMCDME-12345) to analyze +and implement. +``` + +**User:** "EPMCDME-10750" + +**Tech Lead Actions:** +1. Uses brianna skill: `Skill(skill="brianna", args="get EPMCDME-10750 fields: description,summary")` +2. Receives ticket details + +### Phase 2: Technical Analysis + +**Guide Consultation:** +```bash +Read .codemie/guides/api/rest-api-patterns.md +Read .codemie/guides/architecture/service-layer-patterns.md +Read .codemie/guides/integration/cloud-integrations.md +Read .codemie/guides/development/security-patterns.md +Read .codemie/guides/development/error-handling.md +``` + +**Codebase Exploration:** +```bash +# Find similar integrations +Glob pattern="*integration*.py" path="src/codemie/integration/" + +# Check existing document handling +Grep pattern="class.*Document" glob="*.py" path="src/codemie/" + +# Find credential management patterns +Grep pattern="get_secret|KMS|credentials" glob="*.py" output_mode="content" +``` + +**Findings:** +- No existing document analysis service +- Similar integration pattern exists for Confluence +- AWS Secrets Manager used for credentials +- File upload handling exists in datasource layer +- Rate limiting not implemented anywhere + +### Phase 3: Complexity Assessment + +**Tech Lead:** +```markdown +## Implementation Analysis: EPMCDME-10750 + +### Complexity Rating: Complex + +### Reasoning: +- **Multi-Layer Impact**: Requires API, Service, Repository, Integration, and Configuration layers +- **External Dependency**: New third-party service with authentication and rate limits +- **Security Critical**: Credential management, file upload validation, data privacy +- **Missing Patterns**: No existing rate limiting or circuit breaker implementation +- **Extensive Changes**: Estimated 15+ files across multiple subsystems + +### Clarity Assessment: +Partially Clear - Core requirements defined, but several technical decisions needed: +- Which AI service provider? (multiple options available) +- Where to store analysis results? (database vs file system) +- How to handle large files? (chunking, async processing) +- What retry strategy? (exponential backoff, circuit breaker) + +### Affected Components: +- **REST API**: `src/codemie/rest_api/routers/` - New document upload endpoint +- **Service Layer**: `src/codemie/service/` - Document analysis service +- **Integration**: `src/codemie/integration/` - External AI service client +- **Repository**: `src/codemie/repository/` - Analysis result storage +- **Models**: `src/codemie/models/` - Document and analysis models +- **Configuration**: `config/` - Service credentials and settings +- **Security**: `src/codemie/core/security/` - Credential management +- **Error Handling**: `src/codemie/core/exceptions.py` - New exception types +- **Tests**: `tests/` - Unit and integration tests for all layers + +### Risk Factors: +- External API reliability and uptime +- Rate limiting and quota management +- Large file handling and memory usage +- Security: credential leakage, malicious uploads +- Cost: per-request pricing from external service +``` + +### Phase 4: Clarifying Questions + +**Tech Lead uses AskUserQuestion:** +```json +{ + "questions": [ + { + "question": "Which AI document analysis service should be integrated?", + "header": "AI Service", + "multiSelect": false, + "options": [ + { + "label": "AWS Textract", + "description": "AWS native service, already have AWS credentials set up" + }, + { + "label": "Azure Document Intelligence", + "description": "Azure service, would need new Azure setup" + }, + { + "label": "Google Document AI", + "description": "Google service, would need new GCP setup" + } + ] + }, + { + "question": "Where should analysis results be stored?", + "header": "Storage", + "multiSelect": false, + "options": [ + { + "label": "PostgreSQL database", + "description": "Structured storage, easy querying, version control" + }, + { + "label": "S3 bucket", + "description": "File-based storage, good for large results, cheaper" + }, + { + "label": "Elasticsearch", + "description": "Searchable storage, good for analytics, already in use" + } + ] + }, + { + "question": "How should large files be handled?", + "header": "File Handling", + "multiSelect": false, + "options": [ + { + "label": "Synchronous processing", + "description": "Simple, but blocks API during analysis" + }, + { + "label": "Asynchronous processing", + "description": "Complex, requires job queue, non-blocking" + }, + { + "label": "File size limits only", + "description": "Reject files above threshold, keep implementation simple" + } + ] + } + ] +} +``` + +**User Responses:** +- AI Service: AWS Textract (leverage existing AWS setup) +- Storage: PostgreSQL database (structured, fits existing patterns) +- File Handling: Asynchronous processing (better UX, worth the complexity) + +### Phase 5: Recommendation + +**Tech Lead:** +```markdown +### Recommendation + +This feature is Complex and would benefit from architectural planning before implementation. + +**Architectural Decisions Required:** +1. Job queue system (Celery? AWS SQS? Redis Queue?) +2. Rate limiting strategy (token bucket? sliding window?) +3. Circuit breaker implementation (failsafe pattern) +4. File storage during processing (temporary S3? local disk?) +5. Result schema design (flexible JSON? strict tables?) +6. Error recovery and retry mechanism +7. Monitoring and observability hooks + +**Suggested Next Steps:** + +**Option 1: Use Solution Architect Skill (Recommended)** +``` +Use solution-architect skill to create a detailed specification covering: +- System architecture diagram +- Data flow and state management +- Interface contracts +- Security considerations +- Error handling strategy +- Implementation milestones +``` + +This will provide: +- Comprehensive specification document +- Risk mitigation strategies +- Phased implementation plan +- Clear interface definitions + +**Option 2: Proceed with High-Level Plan** +If you're comfortable with complexity, I can: +1. Create feature branch: `EPMCDME-10750` +2. Start with core integration layer +3. Iterate through layers incrementally +4. Add async processing last + +However, this approach may require rework as architectural questions arise. + +**Which approach do you prefer?** +``` + +**User:** "Let's use the solution architect skill first" + +### Phase 6: Solution Architect Handoff + +**Tech Lead:** +```markdown +Excellent choice. I'll invoke the solution-architect skill to create a +comprehensive specification. + +**Context being passed:** +- Jira ticket: EPMCDME-10750 +- Complexity assessment: Complex +- Technical decisions: AWS Textract, PostgreSQL, Async processing +- Affected components: [list from assessment] +- Risk factors: [list from assessment] +``` + +**Tech Lead uses Skill tool:** +``` +Skill(skill="solution-architect", args="Create specification for EPMCDME-10750: +External document analysis integration. Context: AWS Textract integration with +async processing and PostgreSQL storage. Complex feature affecting API, Service, +Integration, Repository layers. Key concerns: rate limiting, credential security, +async job management, error recovery.") +``` + +**Solution Architect Output:** +(Solution architect skill creates detailed specification with architecture diagrams, +interface definitions, implementation phases, etc.) + +### Phase 7: Post-Specification Implementation + +After solution architect completes specification: + +**Tech Lead:** +```markdown +Specification complete. Ready to start implementation following the approved design. + +**Implementation will proceed in phases:** +1. Phase 1: Core integration layer with AWS Textract client +2. Phase 2: Job queue and async processing infrastructure +3. Phase 3: API and service layer endpoints +4. Phase 4: Repository and data persistence +5. Phase 5: Error handling and rate limiting +6. Phase 6: Testing and monitoring + +**Creating feature branch:** +``` + +**Branch Creation:** +```bash +git checkout main +git pull origin main +git checkout -b EPMCDME-10750 +git push -u origin EPMCDME-10750 +``` + +**Tech Lead:** +```markdown +Feature branch created: EPMCDME-10750 + +Starting Phase 1: Core integration layer +Following specification section 3.2... + +[Proceeds with implementation following detailed spec] +``` + +## Outcome + +**Time to Specification:** ~45 minutes (solution architect) +**Time to Implementation:** ~3-5 days (complex feature) +**Files Changed:** 18 +**Lines Added:** ~1,200 +**New Dependencies:** 3 (boto3 for AWS, celery for async, rate-limiter library) +**Complexity Accurate:** Yes - Complex assessment prevented premature implementation + +## Key Success Factors + +1. **Early Complexity Detection**: Identified as Complex before wasting time on incomplete implementation +2. **Clarifying Questions**: Resolved ambiguities before design phase +3. **Specification First**: Solution architect provided clear roadmap +4. **Risk Mitigation**: Security and rate limiting addressed in design +5. **Phased Approach**: Incremental implementation reduced risk +6. **Proper Branch**: Isolated complex work from main branch + +## Comparison: Without Tech Lead Skill + +**If user jumped straight into implementation:** +- ❌ Missed credential security pattern +- ❌ Implemented synchronous processing (bad UX) +- ❌ No rate limiting (API abuse risk) +- ❌ Incomplete error handling +- ❌ Would require significant refactoring +- ❌ Estimated 2-3x time wasted on rework + +**With Tech Lead Skill:** +- ✅ Comprehensive specification first +- ✅ All architectural decisions made upfront +- ✅ Security and resilience patterns applied +- ✅ Clear implementation roadmap +- ✅ Phased delivery possible +- ✅ Clean, well-architected solution diff --git a/.claude/skills/tech-lead/examples/non-jira-task-example.md b/.claude/skills/tech-lead/examples/non-jira-task-example.md new file mode 100644 index 0000000..595b3ae --- /dev/null +++ b/.claude/skills/tech-lead/examples/non-jira-task-example.md @@ -0,0 +1,442 @@ +# Example: Non-Jira Task Implementation + +## Scenario + +User wants to implement: "Improve error messages in the API to be more user-friendly" + +No Jira Ticket - User-provided task description + +## Tech Lead Workflow + +### Phase 1: Requirement Gathering + +**Tech Lead:** +``` +I'll help you implement this task. Let me first understand the requirements better. + +## Task Requirements + +**Goal**: Improve error messages in API to be more user-friendly + +Before we proceed, I need some clarification: +``` + +**Tech Lead uses AskUserQuestion:** +```json +{ + "questions": [ + { + "question": "Which API endpoints should be improved?", + "header": "Scope", + "multiSelect": false, + "options": [ + { + "label": "All endpoints", + "description": "Comprehensive improvement across entire API" + }, + { + "label": "Authentication endpoints", + "description": "Focus on auth-related errors (login, signup, etc.)" + }, + { + "label": "User management endpoints", + "description": "Focus on user CRUD operations" + } + ] + }, + { + "question": "What aspects should be improved?", + "header": "Improvements", + "multiSelect": true, + "options": [ + { + "label": "Error message clarity", + "description": "Make messages more descriptive and actionable" + }, + { + "label": "Error codes", + "description": "Add consistent error codes for client handling" + }, + { + "label": "Validation messages", + "description": "Improve field validation error messages" + } + ] + } + ] +} +``` + +**User Responses:** +- Scope: Authentication endpoints +- Improvements: Error message clarity, Validation messages + +**Tech Lead:** +```markdown +## Task Requirements (Finalized) + +**Goal**: Improve error messages in authentication endpoints + +**Acceptance Criteria**: +- Error messages are clear and actionable +- Validation messages specify which fields have issues +- Messages help users understand what went wrong and how to fix it +- Consistent tone and format across all auth endpoints + +**Scope**: Authentication endpoints (login, signup, password reset, token refresh) + +**Branch Name**: What would you like to name the feature branch? +Suggested: `feature/improve-auth-errors` or `task/improve-auth-errors` +``` + +**User:** "Let's use feature/improve-auth-errors" + +### Phase 2: Technical Analysis + +**Guide Consultation:** +```bash +Read .codemie/guides/api/rest-api-patterns.md +Read .codemie/guides/development/error-handling.md +Read .codemie/guides/development/security-patterns.md +``` + +**Codebase Exploration:** +```bash +# Find authentication routers +Glob pattern="*auth*.py" path="src/codemie/rest_api/routers/" + +# Find existing error handling +Grep pattern="raise.*Exception|ValidationException|AuthenticationException" + glob="*auth*.py" + path="src/codemie/rest_api/routers/" + output_mode="content" -n + +# Check exception definitions +Read file_path="src/codemie/core/exceptions.py" +``` + +**Findings:** +- Auth endpoints in: `src/codemie/rest_api/routers/auth.py` +- Uses exceptions from: `codemie.core.exceptions` +- Current error messages are generic +- Validation uses Pydantic, but messages not customized + +### Phase 3: Complexity Assessment + +**Tech Lead:** +```markdown +## Implementation Analysis: Improve Auth Error Messages + +### Complexity Rating: Medium + +### Reasoning: +- **Multiple Components**: 4 authentication endpoints affected +- **Clear Requirements**: Well-defined goals after clarification +- **Pattern Enhancement**: Improving existing pattern, not creating new one +- **Moderate Scope**: 2-3 files (router, possibly service layer, tests) + +### Clarity Assessment: +Clear - After clarification, requirements are well-defined and actionable + +### Affected Components: +- **Auth Router**: `src/codemie/rest_api/routers/auth.py` - Update error messages in 4 endpoints +- **Auth Service**: `src/codemie/service/auth_service.py` - May need validation message improvements +- **Pydantic Models**: `src/codemie/models/auth.py` - Add custom validation messages +- **Tests**: `tests/rest_api/routers/test_auth.py` - Update test expectations for new messages +``` + +### Phase 4: Recommendation + +**Tech Lead:** +```markdown +### Recommendation + +This task is Medium complexity and can be implemented directly. + +**Suggested Approach:** +1. Create feature branch: `feature/improve-auth-errors` +2. Review existing error messages in auth router +3. Define clear, actionable error message templates +4. Update error handling in each endpoint: + - Login: "Invalid email or password. Please check your credentials and try again." + - Signup: Specific field validation (e.g., "Password must be at least 8 characters") + - Password Reset: Clear status messages for each step + - Token Refresh: Explain why token is invalid +5. Add custom Pydantic validators with friendly messages +6. Update tests to match new error messages +7. Test manually with common error scenarios + +**Key Patterns to Follow:** +- Use `ValidationException` for validation errors +- Use `AuthenticationException` for auth failures +- Keep messages user-friendly (no technical jargon) +- Never expose sensitive information (e.g., "user exists" vs "user doesn't exist") +- Follow security pattern: Don't reveal whether email exists + +Ready to proceed? I'll create the feature branch and start implementation. +``` + +**User:** "Yes, let's do it" + +### Phase 5: Implementation + +**Branch Creation:** +```bash +# Check current state +git branch --show-current +# Output: main + +# Update main first +git pull origin main + +# Create feature branch +git checkout -b feature/improve-auth-errors + +# Verify +git branch --show-current +# Output: feature/improve-auth-errors + +# Push branch +git push -u origin feature/improve-auth-errors +``` + +**Code Implementation:** + +**Step 1: Define Error Message Templates** + +Create constants for consistency: +```python +# In src/codemie/rest_api/routers/auth.py (at top) + +# Error message templates +ERROR_MESSAGES = { + "invalid_credentials": "Invalid email or password. Please check your credentials and try again.", + "account_locked": "Your account has been temporarily locked due to multiple failed login attempts. Please try again in 15 minutes or reset your password.", + "email_exists": "An account with this email already exists. Please log in or use a different email.", + "weak_password": "Password must be at least 8 characters and include uppercase, lowercase, and numbers.", + "invalid_token": "Your session has expired. Please log in again.", + "token_expired": "This link has expired. Please request a new password reset link.", +} +``` + +**Step 2: Update Login Endpoint** + +```python +# Before +@router.post("/login") +async def login(credentials: LoginCredentials): + user = await auth_service.authenticate(credentials) + if not user: + raise AuthenticationException("Authentication failed") + return {"token": create_token(user.id)} + +# After +@router.post("/login") +async def login(credentials: LoginCredentials): + try: + user = await auth_service.authenticate(credentials) + except AccountLockedException: + raise AuthenticationException(ERROR_MESSAGES["account_locked"]) + except InvalidCredentialsException: + raise AuthenticationException(ERROR_MESSAGES["invalid_credentials"]) + + return {"token": create_token(user.id)} +``` + +**Step 3: Update Signup Endpoint with Custom Validators** + +```python +# In src/codemie/models/auth.py +from pydantic import BaseModel, EmailStr, field_validator + +class SignupRequest(BaseModel): + email: EmailStr + password: str + name: str + + @field_validator("password") + @classmethod + def validate_password(cls, v: str) -> str: + if len(v) < 8: + raise ValueError("Password must be at least 8 characters long") + if not any(c.isupper() for c in v): + raise ValueError("Password must contain at least one uppercase letter") + if not any(c.islower() for c in v): + raise ValueError("Password must contain at least one lowercase letter") + if not any(c.isdigit() for c in v): + raise ValueError("Password must contain at least one number") + return v + + @field_validator("name") + @classmethod + def validate_name(cls, v: str) -> str: + if len(v.strip()) < 2: + raise ValueError("Name must be at least 2 characters long") + return v.strip() +``` + +**Step 4: Update Router to Use Custom Messages** + +```python +# In router +@router.post("/signup") +async def signup(request: SignupRequest): + try: + user = await auth_service.create_user(request) + return {"message": "Account created successfully", "user_id": user.id} + except UserAlreadyExistsException: + raise ValidationException(ERROR_MESSAGES["email_exists"]) +``` + +**Step 5: Update Tests** + +```python +# In tests/rest_api/routers/test_auth.py + +def test_login_invalid_credentials(): + response = client.post("/auth/login", json={ + "email": "wrong@example.com", + "password": "wrongpass" + }) + assert response.status_code == 401 + assert response.json()["detail"] == "Invalid email or password. Please check your credentials and try again." + +def test_signup_weak_password(): + response = client.post("/auth/signup", json={ + "email": "newuser@example.com", + "password": "weak", + "name": "Test User" + }) + assert response.status_code == 422 + assert "at least 8 characters" in response.json()["detail"][0]["msg"] +``` + +**Commit Changes:** +```bash +# Stage changes +git add src/codemie/rest_api/routers/auth.py +git add src/codemie/models/auth.py +git add src/codemie/service/auth_service.py +git add tests/rest_api/routers/test_auth.py + +# Commit +git commit -m "feature/improve-auth-errors: Improve authentication error messages + +- Add clear, actionable error messages for all auth endpoints +- Implement custom Pydantic validators with user-friendly messages +- Update login errors to explain authentication failures +- Add specific validation messages for signup (password strength, email format) +- Follow security pattern: Don't reveal whether user exists +- Update tests to match new error message expectations + +Affected endpoints: +- POST /auth/login +- POST /auth/signup +- POST /auth/password-reset +- POST /auth/token-refresh + +Co-Authored-By: Claude Opus 4.5 " + +# Push +git push origin feature/improve-auth-errors +``` + +**Testing:** +```bash +# Run linting +poetry run ruff check --fix src/codemie/ + +# Run tests +poetry run pytest tests/rest_api/routers/test_auth.py -v + +# Manual testing +poetry run uvicorn codemie.rest_api.main:app --reload +# Test in browser at http://localhost:8080/docs +``` + +### Phase 6: Create Pull Request (Optional) + +**Tech Lead:** +```markdown +Implementation complete! Error messages are now: +- Clear and actionable +- User-friendly (no technical jargon) +- Consistent across all auth endpoints +- Security-conscious (don't reveal sensitive info) + +**Changes Summary:** +- 4 files modified +- 75 lines added +- Improved user experience for authentication errors +- All tests passing ✅ + +Would you like me to create a pull request for review? +``` + +**User:** "Yes, create the PR" + +```bash +gh pr create --title "Improve authentication error messages" --body "$(cat <<'EOF' +## Summary +- Add clear, actionable error messages to all authentication endpoints +- Implement custom Pydantic validators with user-friendly messages +- Follow security best practices (don't reveal user existence) + +## Changes +- **Login**: Clear message for invalid credentials +- **Signup**: Specific validation messages for each field +- **Password Reset**: Descriptive status messages +- **Token Refresh**: Explain token invalidity + +## Test Plan +- [x] Unit tests updated and passing +- [x] Manual testing completed +- [x] Linting passes +- [x] Security review completed + +## Examples + +**Before**: "Authentication failed" +**After**: "Invalid email or password. Please check your credentials and try again." + +**Before**: "Validation error" +**After**: "Password must be at least 8 characters and include uppercase, lowercase, and numbers." + +🤖 Generated with Claude Code +EOF +)" +``` + +## Outcome + +**Time to Implementation:** ~1.5 hours +**Files Changed:** 4 +**Lines Added:** 75 +**Complexity Accurate:** Yes - Medium assessment was appropriate +**User Satisfaction:** ✅ Improved UX, clear messages, security maintained + +## Key Success Factors + +1. **Clarifying Questions**: Narrowed scope from "all API" to "auth endpoints" +2. **Structured Requirements**: Documented finalized requirements clearly +3. **Proper Branch Naming**: Feature branch with descriptive name +4. **Pattern Following**: Used existing exception types and patterns +5. **Security Awareness**: Followed security guide (don't reveal user existence) +6. **Comprehensive Testing**: Updated tests to match new behavior +7. **Clear Commits**: Descriptive commit message with context + +## Comparison: Without Tech Lead Skill + +**Without structured approach:** +- ❌ Might improve all endpoints (scope creep) +- ❌ Inconsistent message formats +- ❌ Might reveal sensitive information +- ❌ Forgotten test updates +- ❌ Unclear commit message + +**With Tech Lead Skill:** +- ✅ Scoped correctly through clarification +- ✅ Consistent message templates +- ✅ Security patterns followed +- ✅ Tests updated proactively +- ✅ Comprehensive documentation diff --git a/.claude/skills/tech-lead/examples/simple-feature-example.md b/.claude/skills/tech-lead/examples/simple-feature-example.md new file mode 100644 index 0000000..7e06498 --- /dev/null +++ b/.claude/skills/tech-lead/examples/simple-feature-example.md @@ -0,0 +1,181 @@ +# Example: Simple Feature Implementation + +## Scenario + +User wants to implement: "Add logging to user authentication endpoint" + +Jira Ticket: EPMCDME-10500 + +**Ticket Description:** +``` +As a developer, I want comprehensive logging in the user authentication +endpoint so that we can debug login issues more effectively. + +Acceptance Criteria: +- Log successful authentication attempts +- Log failed authentication attempts with reason +- Include user ID and timestamp +- Use appropriate log levels +``` + +## Tech Lead Workflow + +### Phase 1: Requirement Gathering + +**Tech Lead:** +``` +To begin, provide the Jira ticket ID (e.g., EPMCDME-12345) to analyze +and implement. +``` + +**User:** "EPMCDME-10500" + +**Tech Lead Actions:** +1. Uses brianna skill: `Skill(skill="brianna", args="get EPMCDME-10500 fields: description,summary")` +2. Receives ticket details + +### Phase 2: Technical Analysis + +**Guide Consultation:** +```bash +Read .codemie/guides/development/logging-patterns.md +Read .codemie/guides/api/rest-api-patterns.md +``` + +**Codebase Exploration:** +```bash +# Find authentication endpoint +Grep pattern="def.*auth" glob="*.py" path="src/codemie/rest_api/" + +# Check existing logging patterns +Grep pattern="logger\.(info|error|debug)" glob="*.py" output_mode="content" -n +``` + +**Findings:** +- Auth endpoint in: `src/codemie/rest_api/routers/auth.py` +- Logging pattern established: F-string format, no `extra` parameter +- Logger imported from: `codemie.core.logging` + +### Phase 3: Complexity Assessment + +**Tech Lead:** +```markdown +## Implementation Analysis: EPMCDME-10500 + +### Complexity Rating: Simple + +### Reasoning: +- **Single Component**: Only API layer affected, one endpoint file +- **Clear Requirements**: All acceptance criteria well-defined with examples +- **Established Pattern**: Logging patterns documented and used throughout codebase +- **Minimal Scope**: Single file modification (~10 lines added) + +### Clarity Assessment: +Clear - Requirements specify exactly what to log, when, and at what level + +### Affected Components: +- **Authentication Router**: `src/codemie/rest_api/routers/auth.py` - Add logging statements +``` + +### Phase 4: Recommendation + +**Tech Lead:** +```markdown +### Recommendation + +This feature is Simple complexity and can be implemented directly. + +**Suggested Approach:** +1. Create feature branch: `EPMCDME-10500` +2. Add logging after successful authentication (INFO level) +3. Add logging for failed authentication (WARNING level) +4. Include user_id and timestamp using f-strings +5. Follow logging pattern: `logger.info(f"User {user_id} authenticated at {timestamp}")` + +Ready to proceed? I'll create the feature branch and start implementation. +``` + +**User:** "Yes, let's start" + +### Phase 5: Implementation + +**Branch Creation:** +```bash +# Check current state +git branch --show-current +# Output: main + +# Create feature branch +git checkout -b EPMCDME-10500 + +# Verify +git branch --show-current +# Output: EPMCDME-10500 +``` + +**Code Implementation:** + +Read the file first: +```bash +Read file_path="src/codemie/rest_api/routers/auth.py" +``` + +Edit to add logging: +```python +# Before (line 45): +async def authenticate_user(credentials: AuthCredentials): + user = await auth_service.validate_credentials(credentials) + if user: + return {"token": create_token(user.id)} + raise AuthenticationException("Invalid credentials") + +# After: +async def authenticate_user(credentials: AuthCredentials): + user = await auth_service.validate_credentials(credentials) + if user: + logger.info(f"User authenticated successfully: user_id={user.id} timestamp={datetime.now()}") + return {"token": create_token(user.id)} + + logger.warning(f"Authentication failed: username={credentials.username} timestamp={datetime.now()}") + raise AuthenticationException("Invalid credentials") +``` + +**Testing:** +```bash +# Run linting +poetry run ruff check --fix src/codemie/rest_api/routers/auth.py + +# Run tests +poetry run pytest tests/rest_api/routers/test_auth.py -v +``` + +**Commit:** +```bash +git add src/codemie/rest_api/routers/auth.py +git commit -m "EPMCDME-10500: Add logging to authentication endpoint + +- Log successful authentication with user_id +- Log failed authentication attempts with username +- Include timestamps in all log messages +- Use appropriate log levels (INFO for success, WARNING for failures) + +Co-Authored-By: Claude Opus 4.5 " + +git push -u origin EPMCDME-10500 +``` + +## Outcome + +**Time to Implementation:** ~10 minutes +**Files Changed:** 1 +**Lines Added:** 4 +**Complexity Accurate:** Yes - Simple assessment was correct +**User Satisfaction:** ✅ Quick, focused implementation following patterns + +## Key Success Factors + +1. **Quick Guide Lookup**: Logging pattern guide prevented anti-patterns +2. **Accurate Complexity**: Simple assessment meant no over-engineering +3. **Direct Implementation**: No specification phase needed +4. **Pattern Following**: Consistent with codebase standards +5. **Proper Branch**: Isolated work, clean commit history diff --git a/.claude/skills/tech-lead/references/branch-workflow.md b/.claude/skills/tech-lead/references/branch-workflow.md new file mode 100644 index 0000000..7c69927 --- /dev/null +++ b/.claude/skills/tech-lead/references/branch-workflow.md @@ -0,0 +1,499 @@ +# Git Branch Workflow for Jira Tickets + +## Purpose + +This guide defines the git branching workflow specifically for Jira ticket implementation in the Codemie project. It ensures consistent branch naming, proper isolation, and smooth integration. + +## Branch Naming Convention + +### Standard Format + +``` +EPMCDME-XXXXX +``` + +**Rules:** +- Use ticket ID exactly as it appears in Jira +- No prefixes (no `feature/`, `bugfix/`, etc.) +- No suffixes or descriptions +- Match case exactly (uppercase EPMCDME) + +**Examples:** +```bash +# Correct +git checkout -b EPMCDME-10500 +git checkout -b EPMCDME-9876 + +# Incorrect +git checkout -b feature/EPMCDME-10500 # No prefix +git checkout -b EPMCDME-10500-add-logging # No suffix +git checkout -b epmcdme-10500 # Wrong case +``` + +### Why This Format? + +1. **Traceability**: Direct link to Jira ticket +2. **Automation**: GitLab/GitHub can auto-link commits to tickets +3. **Simplicity**: No ambiguity in naming +4. **Consistency**: Team-wide standard + +## Branch Creation Workflow + +### Step 1: Check Current Status + +Before creating a branch, verify clean working state: + +```bash +# Check current branch +git branch --show-current + +# Check for uncommitted changes +git status + +# Check for stashed changes +git stash list +``` + +**If uncommitted changes exist:** +```bash +# Option 1: Commit them +git add . +git commit -m "WIP: Save current work" + +# Option 2: Stash them +git stash push -m "WIP before EPMCDME-XXXXX" + +# Option 3: Discard them (if safe) +git reset --hard +``` + +### Step 2: Update Main Branch + +Ensure main branch is up to date: + +```bash +# Switch to main +git checkout main + +# Pull latest changes +git pull origin main + +# Verify no conflicts +git status +``` + +### Step 3: Create Feature Branch + +Create branch from updated main: + +```bash +# Create and switch to new branch +git checkout -b EPMCDME-XXXXX + +# Verify you're on the new branch +git branch --show-current +# Should output: EPMCDME-XXXXX + +# Verify branch was created from main +git log --oneline -1 +# Should match latest commit on main +``` + +### Step 4: Push Branch to Remote + +Push the new branch to establish remote tracking: + +```bash +# Push and set upstream +git push -u origin EPMCDME-XXXXX + +# Verify remote tracking +git branch -vv +# Should show: [origin/EPMCDME-XXXXX] +``` + +## Branch Already Exists + +### If Branch Exists Locally + +```bash +# Check if branch exists +git branch --list EPMCDME-XXXXX + +# If exists, you have options: + +# Option 1: Switch to existing branch +git checkout EPMCDME-XXXXX +git pull origin EPMCDME-XXXXX # Update from remote + +# Option 2: Delete and recreate (if safe) +git checkout main +git branch -D EPMCDME-XXXXX # Force delete +git checkout -b EPMCDME-XXXXX + +# Option 3: Create with different name (not recommended) +git checkout -b EPMCDME-XXXXX-v2 +``` + +### If Branch Exists Remotely + +```bash +# Check remote branches +git branch -r | grep EPMCDME-XXXXX + +# If exists remotely: + +# Option 1: Check out remote branch +git fetch origin +git checkout EPMCDME-XXXXX +# Automatically tracks remote branch + +# Option 2: Fetch and create local tracking branch +git fetch origin EPMCDME-XXXXX:EPMCDME-XXXXX +git checkout EPMCDME-XXXXX +``` + +### Conflict Resolution + +If local and remote branches diverged: + +```bash +# Check divergence +git checkout EPMCDME-XXXXX +git fetch origin +git status +# Will show: "Your branch and 'origin/EPMCDME-XXXXX' have diverged" + +# Option 1: Rebase local changes onto remote +git pull --rebase origin EPMCDME-XXXXX + +# Option 2: Merge remote changes +git pull origin EPMCDME-XXXXX + +# Option 3: Force local to match remote (discard local) +git reset --hard origin/EPMCDME-XXXXX + +# Option 4: Force remote to match local (overwrite remote) +git push --force-with-lease origin EPMCDME-XXXXX +``` + +## Working on the Branch + +### Making Commits + +Follow commit message conventions: + +```bash +# Standard commit +git add path/to/changed/files +git commit -m "EPMCDME-XXXXX: Brief description of change" + +# Examples: +git commit -m "EPMCDME-10500: Add logging to user endpoint" +git commit -m "EPMCDME-10500: Implement user validation service" +git commit -m "EPMCDME-10500: Add unit tests for user service" +``` + +**Commit Message Format:** +``` +EPMCDME-XXXXX: + +[Optional detailed explanation] +[Optional breaking changes note] + +Co-Authored-By: Claude Opus 4.5 +``` + +### Keeping Branch Updated + +Regularly sync with main to avoid merge conflicts: + +```bash +# Option 1: Rebase (preferred - cleaner history) +git checkout EPMCDME-XXXXX +git fetch origin +git rebase origin/main + +# If conflicts, resolve and continue: +# 1. Fix conflicts in files +# 2. git add +# 3. git rebase --continue + +# Option 2: Merge (preserves history) +git checkout EPMCDME-XXXXX +git fetch origin +git merge origin/main + +# Push updated branch +git push --force-with-lease origin EPMCDME-XXXXX +``` + +### Pushing Changes + +```bash +# First push (already done in step 4) +git push -u origin EPMCDME-XXXXX + +# Subsequent pushes +git push + +# After rebase (requires force push) +git push --force-with-lease origin EPMCDME-XXXXX +``` + +## Pre-Merge Checklist + +Before creating a merge request: + +```bash +# 1. Ensure all changes committed +git status +# Should show: "nothing to commit, working tree clean" + +# 2. Sync with latest main +git fetch origin +git rebase origin/main + +# 3. Run linting +make ruff +# Or: poetry run ruff check --fix && poetry run ruff format + +# 4. Run tests +poetry run pytest tests/ + +# 5. Verify no debug code +git diff origin/main --name-only | xargs grep -l "TODO\|FIXME\|console.log\|breakpoint()" + +# 6. Push final changes +git push --force-with-lease origin EPMCDME-XXXXX +``` + +## Creating Merge Request + +After implementation is complete: + +```bash +# Create MR using GitLab CLI +gh pr create --title "EPMCDME-XXXXX: " --body "$(cat <<'EOF' +## Summary +- <change 1> +- <change 2> +- <change 3> + +## Test Plan +- [ ] Unit tests pass +- [ ] Manual testing completed +- [ ] Linting passes + +## Related +- Jira: EPMCDME-XXXXX + +🤖 Generated with Claude Code +EOF +)" +``` + +Alternatively, use codemie-mr skill: + +```bash +# Let skill handle MR creation +Use Skill tool with skill="codemie-mr" +``` + +## Branch Cleanup + +After merge: + +```bash +# Switch back to main +git checkout main + +# Pull merged changes +git pull origin main + +# Delete local branch +git branch -d EPMCDME-XXXXX + +# Delete remote branch (usually auto-deleted by GitLab) +git push origin --delete EPMCDME-XXXXX + +# Prune deleted remote branches +git fetch --prune +``` + +## Common Issues and Solutions + +### Issue: Forgot to Create Branch + +If started work on main by mistake: + +```bash +# 1. Create branch from current state +git checkout -b EPMCDME-XXXXX + +# 2. Verify changes came with you +git status + +# 3. Commit changes +git add . +git commit -m "EPMCDME-XXXXX: <description>" + +# 4. Push new branch +git push -u origin EPMCDME-XXXXX + +# 5. Reset main to origin +git checkout main +git reset --hard origin/main +``` + +### Issue: Wrong Branch Name + +If created branch with wrong name: + +```bash +# Rename local branch +git branch -m old-name EPMCDME-XXXXX + +# Delete old remote branch +git push origin --delete old-name + +# Push new branch name +git push -u origin EPMCDME-XXXXX +``` + +### Issue: Committed to Wrong Branch + +If committed to wrong branch: + +```bash +# 1. Note the commit hash +git log --oneline -1 +# Example output: abc1234 EPMCDME-XXXXX: My change + +# 2. Switch to correct branch +git checkout EPMCDME-XXXXX + +# 3. Cherry-pick the commit +git cherry-pick abc1234 + +# 4. Switch back to wrong branch +git checkout wrong-branch + +# 5. Remove the commit +git reset --hard HEAD~1 +``` + +### Issue: Branch Diverged from Main + +If branch has fallen far behind main: + +```bash +# Check how far behind +git checkout EPMCDME-XXXXX +git fetch origin +git log --oneline EPMCDME-XXXXX..origin/main + +# If many commits behind, rebase +git rebase origin/main + +# Resolve conflicts one by one +# After each conflict: +# 1. Fix files +# 2. git add <files> +# 3. git rebase --continue + +# Force push rebased branch +git push --force-with-lease origin EPMCDME-XXXXX +``` + +## Best Practices + +### Do's +✅ Always create branch before starting work +✅ Use exact ticket ID as branch name +✅ Keep branch focused on single ticket +✅ Commit frequently with clear messages +✅ Sync with main regularly +✅ Run linting and tests before pushing +✅ Clean up branches after merge + +### Don'ts +❌ Don't work directly on main +❌ Don't add prefixes or suffixes to branch name +❌ Don't mix multiple tickets in one branch +❌ Don't force push without --force-with-lease +❌ Don't leave branches unmerged for weeks +❌ Don't commit without ticket reference + +## Branch Lifecycle Summary + +``` +1. Update main + git checkout main && git pull origin main + +2. Create feature branch + git checkout -b EPMCDME-XXXXX + +3. Push branch + git push -u origin EPMCDME-XXXXX + +4. Work and commit + git add . && git commit -m "EPMCDME-XXXXX: Change" + git push + +5. Keep updated + git fetch origin && git rebase origin/main + git push --force-with-lease + +6. Create MR + gh pr create ... or use codemie-mr skill + +7. After merge, cleanup + git checkout main && git pull origin main + git branch -d EPMCDME-XXXXX +``` + +## Emergency Procedures + +### Accidentally Deleted Work + +```bash +# Find lost commits +git reflog + +# Restore from reflog +git checkout -b recovery-branch <commit-hash> +``` + +### Accidentally Pushed to Main + +```bash +# If pushed to main (and no one else pulled): +git checkout main +git reset --hard origin/main~1 # Go back 1 commit +git push --force-with-lease origin main + +# Create proper branch +git checkout -b EPMCDME-XXXXX +git cherry-pick <commit-hash> # Get your changes back +``` + +### Branch Completely Broken + +```bash +# Start fresh from main +git checkout main +git pull origin main + +# Create new branch +git checkout -b EPMCDME-XXXXX + +# Cherry-pick good commits from broken branch +git log broken-branch --oneline +git cherry-pick <good-commit-1> +git cherry-pick <good-commit-2> + +# Delete broken branch +git branch -D broken-branch +git push origin --delete broken-branch +``` diff --git a/.claude/skills/tech-lead/references/complexity-assessment-guide.md b/.claude/skills/tech-lead/references/complexity-assessment-guide.md new file mode 100644 index 0000000..3e8e80f --- /dev/null +++ b/.claude/skills/tech-lead/references/complexity-assessment-guide.md @@ -0,0 +1,415 @@ +# Complexity Assessment Guide + +## Purpose + +This guide provides detailed criteria and examples for assessing feature complexity when working with Jira tickets. Accurate complexity assessment ensures appropriate planning and implementation approaches. + +## Complexity Dimensions + +### 1. Component Scope + +**Simple:** +- Single component (API, Service, or Repository) +- Self-contained changes +- No cross-cutting concerns +- Example: Add new field to existing endpoint + +**Medium:** +- 2-3 components across layers +- Coordination between API and Service layers +- Minor database schema changes +- Example: Add new endpoint with business logic and data access + +**Complex:** +- 4+ components across multiple subsystems +- New integrations or external services +- Database migrations affecting multiple tables +- Example: Add new workflow with agent, tools, and external API integration + +### 2. Requirements Clarity + +**Clear:** +- All acceptance criteria defined +- No ambiguous terms +- Implementation path obvious +- Existing patterns directly applicable + +**Partially Clear:** +- Core requirements defined +- Some details need clarification +- Minor assumptions required +- May need 1-2 clarifying questions + +**Unclear:** +- Vague acceptance criteria +- Multiple interpretations possible +- Significant architectural decisions needed +- Requires specification or multiple clarifications + +### 3. Technical Risk + +**Low Risk (Simple):** +- Using well-established patterns +- No performance concerns +- No security implications +- Rollback is straightforward + +**Medium Risk (Medium):** +- Some new patterns or approaches +- Minor performance considerations +- Standard security measures apply +- May need feature flag + +**High Risk (Complex):** +- Novel implementation required +- Performance/scalability critical +- Security-sensitive operations +- Difficult to rollback +- External dependencies + +### 4. File Change Estimate + +**Simple:** +- 1-3 files modified +- No new files needed (or 1 new file) +- Changes are localized + +**Medium:** +- 4-8 files modified +- 1-3 new files created +- Changes span multiple directories + +**Complex:** +- 9+ files modified +- 4+ new files created +- Changes affect project structure + +### 5. Dependencies + +**Simple:** +- No new dependencies +- Works with existing libraries +- No version conflicts + +**Medium:** +- 1-2 new dependencies +- Minor version updates +- Standard libraries + +**Complex:** +- 3+ new dependencies +- Major version updates required +- Custom integrations needed +- Potential dependency conflicts + +## Complexity Matrix + +Score each dimension (1=Simple, 2=Medium, 3=Complex): + +| Total Score | Complexity | +|-------------|------------| +| 5-7 | Simple | +| 8-11 | Medium | +| 12-15 | Complex | + +Example scoring: +- Component Scope: 2 (2 components) +- Requirements: 1 (Clear) +- Technical Risk: 1 (Low) +- File Changes: 2 (5 files) +- Dependencies: 1 (None) +- **Total: 7 = Simple** + +## Complexity Assessment Template + +```markdown +## Complexity Analysis: [TICKET-ID] + +### Component Scope: [1-3] +- Affected: [list components] +- Layers: [API/Service/Repository/etc.] + +### Requirements Clarity: [1-3] +- Status: [Clear/Partially Clear/Unclear] +- Gaps: [any unclear items] + +### Technical Risk: [1-3] +- Risk factors: [list] +- Mitigation: [if applicable] + +### File Change Estimate: [1-3] +- Modified: [count] files +- New: [count] files +- Affected directories: [list] + +### Dependencies: [1-3] +- New packages: [list or "none"] +- Version changes: [list or "none"] + +### Total Score: [sum]/15 + +### Final Complexity: [Simple | Medium | Complex] +``` + +## Example Assessments + +### Example 1: Add Logging to Existing Endpoint (Simple) + +```markdown +## Complexity Analysis: EPMCDME-10101 + +### Component Scope: 1 +- Affected: Single API endpoint +- Layers: API only + +### Requirements Clarity: 1 +- Status: Clear +- Gaps: None - logging pattern documented + +### Technical Risk: 1 +- Risk factors: None +- Mitigation: N/A + +### File Change Estimate: 1 +- Modified: 1 file (router file) +- New: 0 files +- Affected directories: rest_api/routers/ + +### Dependencies: 1 +- New packages: None +- Version changes: None + +### Total Score: 5/15 + +### Final Complexity: Simple + +### Reasoning: +- **Isolated Change**: Only API layer affected +- **Clear Pattern**: Logging patterns documented in guides +- **Low Risk**: Non-functional addition, no business logic change +- **Minimal Scope**: Single file modification +``` + +### Example 2: Create New Agent with Custom Tool (Medium) + +```markdown +## Complexity Analysis: EPMCDME-10202 + +### Component Scope: 2 +- Affected: Agents subsystem, Tools subsystem +- Layers: Agent orchestration + tool implementation + +### Requirements Clarity: 2 +- Status: Partially Clear +- Gaps: Tool behavior details need clarification + +### Technical Risk: 2 +- Risk factors: LLM token usage, tool reliability +- Mitigation: Add usage tracking, error handling + +### File Change Estimate: 2 +- Modified: 2 files (agent config, tool registry) +- New: 3 files (agent class, tool class, tests) +- Affected directories: agents/, agents/tools/ + +### Dependencies: 1 +- New packages: None (using existing LangChain) +- Version changes: None + +### Total Score: 9/15 + +### Final Complexity: Medium + +### Reasoning: +- **Multi-Component**: Agent + tool coordination required +- **Pattern Available**: LangChain patterns documented +- **Moderate Risk**: LLM usage needs monitoring +- **Multiple Files**: 5 files total, but following established patterns +``` + +### Example 3: Integrate New Cloud Service (Complex) + +```markdown +## Complexity Analysis: EPMCDME-10303 + +### Component Scope: 3 +- Affected: API, Service, Repository, Configuration, Integration layer +- Layers: Full stack + external service + +### Requirements Clarity: 2 +- Status: Partially Clear +- Gaps: Authentication method, data mapping, error handling strategy + +### Technical Risk: 3 +- Risk factors: External API reliability, security (credentials), rate limits +- Mitigation: Circuit breaker, credential management, retry logic + +### File Change Estimate: 3 +- Modified: 8 files (configs, existing services) +- New: 6 files (integration service, models, tests, configs) +- Affected directories: service/, integration/, configs/, repository/ + +### Dependencies: 3 +- New packages: Cloud SDK (major dependency), auth library +- Version changes: May require Python version update + +### Total Score: 14/15 + +### Final Complexity: Complex + +### Reasoning: +- **Cross-Cutting**: Affects multiple subsystems and all layers +- **High Risk**: External dependency with security implications +- **Architectural Impact**: New integration pattern, credential management +- **Extensive Changes**: 14 files across entire codebase +``` + +## Red Flags for Complexity + +Automatically consider as Complex if ticket contains: + +### Technical Red Flags +- "Migrate" or "Refactor" large subsystems +- "Real-time" or "Streaming" requirements +- "Performance" or "Scalability" as primary concern +- "Security" or "Compliance" requirements +- "Integration" with new external service + +### Scope Red Flags +- Affects authentication or authorization +- Changes database schema significantly +- Requires data migration +- Touches core shared utilities +- Affects multiple workflows or agents + +### Clarity Red Flags +- Vague acceptance criteria +- Multiple stakeholders with different expectations +- "Similar to X but different" requirements +- Phrases like "we'll figure it out" or "TBD" + +## Questions to Ask for Clarity + +### For Partially Clear Requirements + +**Data Questions:** +- What is the expected data format? +- What are the validation rules? +- What is the data volume? + +**Behavior Questions:** +- What happens in edge cases? +- What are the error handling expectations? +- What is the expected performance? + +**Integration Questions:** +- Which systems need to be notified? +- What is the authentication method? +- What are rate limits or quotas? + +### For Unclear Requirements + +**Strategic Questions:** +- What problem are we solving? +- Who are the end users? +- What is the success metric? +- Are there existing alternatives? + +**Technical Questions:** +- What are the non-functional requirements? +- What is the expected load? +- What are the SLAs? +- What are the security requirements? + +**Scoping Questions:** +- Is this a proof of concept or production feature? +- What is the timeline? +- Can this be broken into smaller tickets? + +## Assessment Output Format + +Always provide assessment in this structure: + +```markdown +## Implementation Analysis: EPMCDME-XXXXX + +### Complexity Rating: [Simple | Medium | Complex] + +### Reasoning: +- **[Dimension 1]**: [Score justification] +- **[Dimension 2]**: [Score justification] +- **[Dimension 3]**: [Score justification] +- **[Dimension 4]**: [Score justification - optional] + +### Clarity Assessment: +[Clear | Partially Clear | Unclear] - [Explanation] + +### Affected Components: +- **[Component]**: `path/to/file` - [Nature of change] +- **[Component]**: `path/to/file` - [Nature of change] +- **[Component]**: `path/to/file` - [Nature of change] + +### Risk Factors: +- [Risk 1] +- [Risk 2] + +### Implementation Estimate: +- Files to modify: [count] +- New files: [count] +- New dependencies: [list or "none"] +``` + +## Best Practices + +### Do's +✅ Consider all five dimensions +✅ Provide evidence for each score +✅ Reference specific files and patterns +✅ Identify concrete risks +✅ Use objective criteria + +### Don'ts +❌ Rely on gut feeling alone +❌ Ignore available patterns +❌ Underestimate integration complexity +❌ Skip risk assessment +❌ Guess at file counts + +## Handling Edge Cases + +### Ticket Seems Simple But... + +If initial assessment seems Simple but has red flags: +1. Re-evaluate Technical Risk dimension +2. Check for hidden dependencies +3. Verify requirements are truly clear +4. Consider upgrading to Medium + +### User Disagrees with Assessment + +If user believes complexity is different: +1. Ask for their reasoning +2. Identify which dimensions differ +3. Reassess with additional context +4. Document the agreed complexity + +### Borderline Cases (Score 7-8 or 11-12) + +For borderline scores: +- Lean toward higher complexity if risks are present +- Lean toward lower if strong patterns exist +- Let user make final call +- Document uncertainty + +## Continuous Improvement + +After implementation: +1. Compare actual vs estimated complexity +2. Note which dimensions were misjudged +3. Update assessment criteria +4. Share learnings with team + +Track accuracy over time: +- Simple tickets: Should complete in 1-2 days +- Medium tickets: Should complete in 3-5 days +- Complex tickets: May need specification phase first