aios-core 4.2.15 → 4.4.0

package/.aios-core/development/tasks/resolve-github-issue.md

@@ -0,0 +1,608 @@
+# resolve-github-issue.md
+
+**Task**: Investigate and Resolve GitHub Issue
+
+**Purpose**: End-to-end workflow for investigating, planning, implementing, testing, and closing a GitHub issue following project standards (Constitution, Story-Driven, Quality Gates).
+
+**When to use**: After selecting an issue from triage, via `@devops *resolve-issue {number}` or user request like "resolve issue #138".
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Investigate, fix, test, commit, push, close — minimal prompts
+- Decisions logged but not confirmed
+- **Best for:** Quick fixes (XS/S effort), well-defined bugs, chore tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Checkpoints at investigation, plan, implementation, and push
+- User confirms approach before major changes
+- **Best for:** Most issues, medium complexity
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Full investigation + research + detailed plan BEFORE any code
+- User approves plan, then autonomous execution
+- **Best for:** Complex issues, multi-file changes, unknown root cause
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: resolveGithubIssue()
+responsavel: Gage (Operator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: issue_number
+  tipo: number
+  origem: User Input
+  obrigatorio: true
+  validacao: Must be a valid open GitHub issue number
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatorio: false
+  validacao: yolo|interactive|pre-flight
+  default: interactive
+
+- campo: branch
+  tipo: string
+  origem: Auto-detect or User Input
+  obrigatorio: false
+  validacao: Valid git branch name
+  default: Current branch
+
+**Saida:**
+- campo: resolution_summary
+  tipo: object
+  destino: GitHub Issue Comment + User Display
+  persistido: true
+  formato: |
+    { issue: number, commit: sha, files_changed: number, tests: pass/fail, closed: boolean }
+
+- campo: commit_sha
+  tipo: string
+  destino: Git
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] GitHub CLI authenticated (gh auth status)
+    tipo: pre-condition
+    blocker: true
+    error_message: "GitHub CLI not authenticated. Run: gh auth login"
+
+  - [ ] Issue exists and is open
+    tipo: pre-condition
+    blocker: true
+    validacao: |
+      Run: gh issue view {issue_number} --json state
+      Must return state: "OPEN"
+    error_message: "Issue #{issue_number} not found or already closed"
+
+  - [ ] Working tree is clean (no uncommitted changes)
+    tipo: pre-condition
+    blocker: false
+    validacao: |
+      Run: git status --porcelain
+      If dirty: warn user, suggest stash or commit first
+    error_message: "Uncommitted changes detected. Commit or stash before proceeding."
+
+  - [ ] On appropriate branch
+    tipo: pre-condition
+    blocker: false
+    validacao: |
+      Check current branch with: git branch --show-current
+      Warn if on main/master (suggest creating feature branch)
+```
+
+---
+
+## Workflow Steps
+
+### Phase 1: Investigate (understand the issue)
+
+**Goal:** Fully understand the problem before writing any code.
+
+```yaml
+steps:
+  1_fetch_issue:
+    command: gh issue view {issue_number} --json title,body,labels,comments,assignees
+    output: issue_data
+    purpose: Get full issue details including comments with context
+
+  2_analyze_issue:
+    action: Read issue body and comments carefully
+    extract:
+      - What is the reported problem?
+      - What is the expected behavior?
+      - What is the actual behavior?
+      - Are there reproduction steps?
+      - Are there error messages or logs?
+      - Which files/modules are likely affected?
+    output: issue_analysis
+
+  3_codebase_investigation:
+    action: Search codebase for affected code
+    tools:
+      - Grep: Search for keywords from issue (error messages, function names, file paths)
+      - Glob: Find related files by pattern
+      - Read: Read suspect files to understand current behavior
+    output: affected_files[]
+    purpose: Confirm root cause and scope of change
+
+  4_research_if_needed:
+    condition: Issue involves external standards, APIs, or unfamiliar technology
+    action: |
+      Use /tech-search skill for deep research:
+        - External format specifications (e.g., Copilot .agent.md format)
+        - API documentation changes
+        - Best practices for the technology involved
+      Research output saved to docs/research/{date}-{slug}/
+    output: research_findings (optional)
+    examples:
+      - Issue #138: Required /tech-search for GitHub Copilot custom agents format
+      - Issue #159: No research needed (simple rename across codebase)
+```
+
+**Checkpoint (Interactive/Pre-Flight modes):**
+
+Present investigation summary to user:
+```
+Investigation Summary for Issue #{number}:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Problem: {description}
+Root Cause: {root_cause}
+Affected Files: {count} files
+  - {file1}
+  - {file2}
+  - ...
+Research: {needed/not_needed/completed}
+Estimated Effort: {XS/S/M/L/XL}
+
+Proposed Approach:
+  1. {step1}
+  2. {step2}
+  ...
+
+Proceed with implementation? (Y/n)
+```
+
+### Phase 2: Plan (design the solution)
+
+**Goal:** Create a clear implementation plan before touching code.
+
+```yaml
+steps:
+  1_identify_changes:
+    action: List all files that need to be created, modified, or deleted
+    output: change_manifest[]
+    format: |
+      | Action | File | Description |
+      |--------|------|-------------|
+      | CREATE | path/to/new-file.js | New component for X |
+      | MODIFY | path/to/existing.js | Update function Y |
+      | DELETE | path/to/old-file.md | Replaced by new format |
+      | RENAME | old-name → new-name | Extension change |
+
+  2_check_dependencies:
+    action: Verify if changes affect other systems
+    checks:
+      - Does this change affect the installer? (packages/installer/)
+      - Does this change affect IDE sync? (.aios-core/infrastructure/scripts/ide-sync/)
+      - Does this change affect tests? (tests/)
+      - Does this change affect documentation? (docs/)
+      - Does this change affect CI/CD? (.github/workflows/)
+      - Does this change affect other agents? (.aios-core/development/agents/)
+    output: dependency_impacts[]
+
+  3_verify_ids_gate:
+    action: IDS G4 - Check Entity Registry for reusable patterns
+    gate: G4 (Dev Context - Informational, non-blocking)
+    checks:
+      - Are there existing patterns/utilities that solve part of this?
+      - Can existing code be ADAPTED (< 30% change) instead of creating new?
+      - If creating new entities, prepare registry entry
+    output: ids_decision (REUSE/ADAPT/CREATE per entity)
+
+  4_plan_tests:
+    action: Determine test strategy
+    checks:
+      - Existing tests that need updating?
+      - New tests required?
+      - Manual validation steps?
+    output: test_plan
+```
+
+### Phase 3: Implement (make the changes)
+
+**Goal:** Execute the plan with quality and safety.
+
+```yaml
+steps:
+  1_implement_changes:
+    action: Apply changes following the plan from Phase 2
+    rules:
+      - Follow project conventions (CLAUDE.md)
+      - Use absolute imports, never relative
+      - No `any` in TypeScript
+      - kebab-case files, PascalCase components
+      - Conventional Commits for commit message
+      - Reference issue number in commit: "fix(scope): description (#N)"
+
+  2_parallel_execution:
+    condition: Multiple independent changes can be made simultaneously
+    action: Use Task tool with subagents for parallel work
+    examples:
+      - Issue #159: 5 parallel agents for bulk rename across 136 files
+      - Issue #138: Sequential (transformer → config → sync → cleanup)
+    guidance: |
+      Use parallel agents when:
+        - Changes are to independent files with no cross-dependencies
+        - Bulk operations across many files (>10 files with similar changes)
+        - Research + implementation can overlap
+      Use sequential when:
+        - Later changes depend on earlier ones
+        - Config changes must be tested before file operations
+        - New code must exist before references to it
+
+  3_handle_edge_cases:
+    action: Watch for common pitfalls from past sessions
+    known_pitfalls:
+      - Email addresses inside strings may match rename patterns (Issue #159: security@synkra/aios-core.dev)
+      - YAML parser converts "KEY: value" to objects, not strings (Issue #138: core_principles)
+      - Windows bash escapes `!` in inline scripts (use temp .js files instead of node -e)
+      - Replace_all may match unintended occurrences (always verify with Grep after bulk changes)
+      - Submodule `pro` shows as modified even when unchanged (ignore in git status)
+    mitigation: |
+      After bulk changes:
+        1. Grep for the old pattern to verify completeness
+        2. Grep for corruption patterns (partial replacements)
+        3. Read a sample of changed files to verify correctness
+
+  4_regenerate_manifests:
+    condition: Changes affect files tracked by install manifest
+    action: |
+      Run: node scripts/generate-install-manifest.js
+      This regenerates .aios-core/install-manifest.yaml
+    when: Any file in .aios-core/ or packages/ is created, modified, or deleted
+
+  5_run_ide_sync:
+    condition: Changes affect agent definitions or IDE sync system
+    action: |
+      Run: node .aios-core/infrastructure/scripts/ide-sync/index.js sync --verbose
+      Verify all IDEs sync without errors
+    when: Changes to .aios-core/development/agents/ or ide-sync/
+```
+
+### Phase 4: Validate (test and verify)
+
+**Goal:** Ensure changes are correct and don't break anything.
+
+```yaml
+steps:
+  1_run_tests:
+    command: npm test
+    must_pass: true
+    on_failure: |
+      Analyze test output, fix failures, re-run.
+      Do NOT proceed to commit if tests fail.
+
+  2_verify_changes:
+    action: Manual verification
+    checks:
+      - [ ] All files listed in plan were changed
+      - [ ] No unintended files were modified
+      - [ ] Grep confirms old patterns are gone (for bulk changes)
+      - [ ] Sample output looks correct (for format changes)
+      - [ ] No secrets or credentials in changed files
+
+  3_lint_check:
+    command: npm run lint
+    must_pass: false
+    note: Warn if lint fails but don't block (some projects may not have lint)
+```
+
+### Phase 5: Commit & Push
+
+**Goal:** Create a clean, well-documented commit and push to remote.
+
+```yaml
+steps:
+  1_stage_changes:
+    action: Stage ONLY files related to this issue
+    rules:
+      - Use specific file names, NOT "git add -A" or "git add ."
+      - Exclude unrelated changes (pro submodule, coverage files, etc.)
+      - Exclude .env, credentials, and sensitive files
+      - Include regenerated manifests if applicable
+
+  2_commit:
+    action: Create commit following Conventional Commits
+    format: |
+      {type}({scope}): {description} (#{issue_number})
+
+      {body - what was changed and why}
+
+      Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+    type_map:
+      BUG: fix
+      FEATURE: feat
+      ENHANCEMENT: feat
+      DOCS: docs
+      CHORE: chore
+      SECURITY: fix
+
+  3_push:
+    command: git push origin {branch}
+    authority: "@devops EXCLUSIVE — only this agent pushes to remote"
+    on_failure: |
+      Check if branch has upstream: git push -u origin {branch}
+      Check for conflicts: git pull --rebase origin {branch}
+
+  4_close_issue:
+    command: |
+      gh issue close {issue_number} --comment "$(cat <<'EOF'
+      ## Resolved in commit {sha}
+
+      ### Root Cause
+      {root_cause_description}
+
+      ### Changes
+      {numbered_list_of_changes}
+
+      ### Validation
+      - {test_count} tests passing
+      - {validation_details}
+      EOF
+      )"
+    purpose: Close with detailed resolution comment for future reference
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] All planned changes implemented
+    tipo: post-condition
+    blocker: true
+
+  - [ ] Tests pass (npm test exit code 0)
+    tipo: post-condition
+    blocker: true
+
+  - [ ] Changes committed with proper message referencing issue
+    tipo: post-condition
+    blocker: true
+
+  - [ ] Changes pushed to remote
+    tipo: post-condition
+    blocker: true
+
+  - [ ] Issue closed with resolution comment
+    tipo: post-condition
+    blocker: true
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Issue root cause identified and documented in close comment
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Fix addresses the reported problem completely
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] No regressions introduced (all existing tests pass)
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Commit follows Conventional Commits format with issue reference
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Issue closed on GitHub with detailed resolution
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] If research was needed, saved to docs/research/
+    tipo: acceptance-criterion
+    blocker: false
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** gh (GitHub CLI)
+  - **Purpose:** Fetch issue details, close issues, add comments
+  - **Source:** System CLI
+  - **Required:** true
+
+- **Tool:** git
+  - **Purpose:** Stage, commit, push changes
+  - **Source:** System CLI
+  - **Required:** true
+  - **Authority:** @devops EXCLUSIVE for push operations
+
+- **Tool:** npm
+  - **Purpose:** Run tests (npm test), lint, build
+  - **Source:** System CLI
+  - **Required:** true
+
+- **Tool:** /tech-search (skill)
+  - **Purpose:** Deep research when issue involves external specs/APIs
+  - **Source:** .claude/skills/tech-search
+  - **Required:** false (only when research needed)
+
+- **Tool:** Grep/Glob/Read
+  - **Purpose:** Codebase investigation during Phase 1
+  - **Source:** Claude Code native tools
+  - **Required:** true
+
+- **Tool:** Task (subagents)
+  - **Purpose:** Parallel execution for bulk operations
+  - **Source:** Claude Code native tool
+  - **Required:** false (only for large-scope changes)
+
+---
+
+## Dependencies
+
+```yaml
+dependencies:
+  tasks:
+    - triage-github-issues.md        # Upstream: triage feeds into resolve
+    - github-devops-pre-push-quality-gate.md  # Optional: full quality gate before push
+  checklists: []
+  templates: []
+  skills:
+    - tech-search                     # For deep research when needed
+  tools:
+    - gh (GitHub CLI)
+    - git
+    - npm
+```
+
+---
+
+## Error Handling
+
+**Strategy:** checkpoint-and-recover
+
+**Common Errors:**
+
+1. **Error:** Issue already closed
+   - **Cause:** Someone else closed the issue
+   - **Resolution:** Verify with `gh issue view`, report to user
+   - **Recovery:** Skip close step, still commit if fix was needed
+
+2. **Error:** Tests fail after implementation
+   - **Cause:** Code change introduced regression
+   - **Resolution:** Analyze test output, fix the issue
+   - **Recovery:** Do NOT push. Fix tests first, then retry Phase 4-5
+
+3. **Error:** Push rejected (behind remote)
+   - **Cause:** Remote has new commits
+   - **Resolution:** `git pull --rebase origin {branch}` then retry push
+   - **Recovery:** If rebase has conflicts, resolve and re-test
+
+4. **Error:** Bulk replace corrupts unintended strings
+   - **Cause:** Pattern matches inside URLs, emails, or compound identifiers
+   - **Resolution:** Grep for corruption patterns immediately after replace
+   - **Recovery:** Manual fix of affected files, re-verify
+   - **Prevention:** Use targeted edits instead of global replace when pattern is ambiguous
+
+5. **Error:** Research needed but /tech-search unavailable
+   - **Cause:** Skill not loaded or external search failing
+   - **Resolution:** Fall back to manual WebSearch + WebFetch
+   - **Recovery:** Document findings manually in docs/research/
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected:
+  XS_issue: 5-15 min
+  S_issue: 15-30 min
+  M_issue: 30-60 min
+  L_issue: 1-2 hours
+  XL_issue: 2-4 hours
+cost_estimated: $0.01-0.10 (depends on complexity and research)
+token_usage: ~5,000-50,000 tokens
+```
+
+---
+
+## Metadata
+
+```yaml
+story: N/A (operational task)
+version: 1.0.0
+dependencies:
+  tasks:
+    - triage-github-issues.md
+    - github-devops-pre-push-quality-gate.md
+  skills:
+    - tech-search
+tags:
+  - devops
+  - issue-management
+  - implementation
+  - quality-gates
+created_at: 2026-02-21
+updated_at: 2026-02-21
+related_tasks:
+  - triage-github-issues.md
+  - github-devops-pre-push-quality-gate.md
+  - github-devops-github-pr-automation.md
+```
+
+---
+
+## Lessons Learned (from past sessions)
+
+These patterns were identified from real issue resolution sessions and should guide execution:
+
+### Issue #159 (Bulk Rename) — Parallel + Edge Cases
+- **Pattern:** 5 parallel agents for 136 files, split by directory
+- **Pitfall:** `@synkra/aios-core` inside email `security@synkra/aios-core.dev` was corrupted
+- **Lesson:** Always Grep for edge cases AFTER bulk replacements
+
+### Issue #138 (Copilot Format) — Research-First
+- **Pattern:** /tech-search before implementation, 6-phase plan from research
+- **Pitfall:** YAML parsed `CRITICAL: value` as `{CRITICAL: value}` object instead of string
+- **Lesson:** Handle both string and object formats when processing YAML arrays
+
+### Issue #174 (Package Name) — Quick Win
+- **Pattern:** Small, focused fix in 1 file, immediate validation
+- **Lesson:** Quick wins should still follow full validate → commit → push → close cycle
+
+### Email Removal — User Feedback Mid-Session
+- **Pattern:** User noticed non-existent emails during issue resolution
+- **Lesson:** Be responsive to user feedback even when working on a different issue
+
+---
+
+## Integration with @devops Agent
+
+Called via `@devops *resolve-issue {number}` command.
+
+**Upstream:** `*triage-issues` → user selects issue → `*resolve-issue {number}`
+**Downstream:** After resolution → `*triage-issues` again for next issue (if in batch mode)