Update .gitignore to include additional file types and directories for Python projects, enhancing environment management and build artifacts exclusion.

2026-04-22 22:36:32 +00:00 · 2026-03-20 21:28:16 +02:00
parent 9e5b0f2cc2
commit 7556f3b012
65 changed files with 9165 additions and 7 deletions
@@ -0,0 +1,471 @@
+---
+name: refactor
+description: |
+  Structured refactoring workflow (6-phase method) with three execution modes:
+  - Full Refactoring: all 6 phases — baseline, discovery, analysis, safety net, execution, hardening
+  - Targeted Refactoring: skip discovery if docs exist, focus on a specific component/area
+  - Quick Assessment: phases 0-2 only, outputs a refactoring plan without execution
+  Supports project mode (_docs/ structure) and standalone mode (@file.md).
+  Trigger phrases:
+  - "refactor", "refactoring", "improve code"
+  - "analyze coupling", "decoupling", "technical debt"
+  - "refactoring assessment", "code quality improvement"
+category: evolve
+tags: [refactoring, coupling, technical-debt, performance, hardening]
+disable-model-invocation: true
+---
+
+# Structured Refactoring (6-Phase Method)
+
+Transform existing codebases through a systematic refactoring workflow: capture baseline, document current state, research improvements, build safety net, execute changes, and harden.
+
+## Core Principles
+
+- **Preserve behavior first**: never refactor without a passing test suite
+- **Measure before and after**: every change must be justified by metrics
+- **Small incremental changes**: commit frequently, never break tests
+- **Save immediately**: write artifacts to disk after each phase; never accumulate unsaved work
+- **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user
+
+## Context Resolution
+
+Determine the operating mode based on invocation before any other logic runs.
+
+**Project mode** (no explicit input file provided):
+- PROBLEM_DIR: `_docs/00_problem/`
+- SOLUTION_DIR: `_docs/01_solution/`
+- COMPONENTS_DIR: `_docs/02_components/`
+- TESTS_DIR: `_docs/02_tests/`
+- REFACTOR_DIR: `_docs/04_refactoring/`
+- All existing guardrails apply.
+
+**Standalone mode** (explicit input file provided, e.g. `/refactor @some_component.md`):
+- INPUT_FILE: the provided file (treated as component/area description)
+- REFACTOR_DIR: `_standalone/refactoring/`
+- Guardrails relaxed: only INPUT_FILE must exist and be non-empty
+- `acceptance_criteria.md` is optional — warn if absent
+
+Announce the detected mode and resolved paths to the user before proceeding.
+
+## Mode Detection
+
+After context resolution, determine the execution mode:
+
+1. **User explicitly says** "quick assessment" or "just assess" → **Quick Assessment**
+2. **User explicitly says** "refactor [component/file/area]" with a specific target → **Targeted Refactoring**
+3. **Default** → **Full Refactoring**
+
+| Mode | Phases Executed | When to Use |
+|------|----------------|-------------|
+| **Full Refactoring** | 0 → 1 → 2 → 3 → 4 → 5 | Complete refactoring of a system or major area |
+| **Targeted Refactoring** | 0 → (skip 1 if docs exist) → 2 → 3 → 4 → 5 | Refactor a specific component; docs already exist |
+| **Quick Assessment** | 0 → 1 → 2 | Produce a refactoring roadmap without executing changes |
+
+Inform the user which mode was detected and confirm before proceeding.
+
+## Prerequisite Checks (BLOCKING)
+
+**Project mode:**
+1. PROBLEM_DIR exists with `problem.md` (or `problem_description.md`) — **STOP if missing**, ask user to create it
+2. If `acceptance_criteria.md` is missing: **warn** and ask whether to proceed
+3. Create REFACTOR_DIR if it does not exist
+4. If REFACTOR_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**
+
+**Standalone mode:**
+1. INPUT_FILE exists and is non-empty — **STOP if missing**
+2. Warn if no `acceptance_criteria.md` provided
+3. Create REFACTOR_DIR if it does not exist
+
+## Artifact Management
+
+### Directory Structure
+
+```
+REFACTOR_DIR/
+├── baseline_metrics.md          (Phase 0)
+├── discovery/
+│   ├── components/
+│   │   └── [##]_[name].md       (Phase 1)
+│   ├── solution.md              (Phase 1)
+│   └── system_flows.md          (Phase 1)
+├── analysis/
+│   ├── research_findings.md     (Phase 2)
+│   └── refactoring_roadmap.md   (Phase 2)
+├── test_specs/
+│   └── [##]_[test_name].md      (Phase 3)
+├── coupling_analysis.md         (Phase 4)
+├── execution_log.md             (Phase 4)
+├── hardening/
+│   ├── technical_debt.md        (Phase 5)
+│   ├── performance.md           (Phase 5)
+│   └── security.md              (Phase 5)
+└── FINAL_report.md              (after all phases)
+```
+
+### Save Timing
+
+| Phase | Save immediately after | Filename |
+|-------|------------------------|----------|
+| Phase 0 | Baseline captured | `baseline_metrics.md` |
+| Phase 1 | Each component documented | `discovery/components/[##]_[name].md` |
+| Phase 1 | Solution synthesized | `discovery/solution.md`, `discovery/system_flows.md` |
+| Phase 2 | Research complete | `analysis/research_findings.md` |
+| Phase 2 | Roadmap produced | `analysis/refactoring_roadmap.md` |
+| Phase 3 | Test specs written | `test_specs/[##]_[test_name].md` |
+| Phase 4 | Coupling analyzed | `coupling_analysis.md` |
+| Phase 4 | Execution complete | `execution_log.md` |
+| Phase 5 | Each hardening track | `hardening/<track>.md` |
+| Final | All phases done | `FINAL_report.md` |
+
+### Resumability
+
+If REFACTOR_DIR already contains artifacts:
+
+1. List existing files and match to the save timing table
+2. Identify the last completed phase based on which artifacts exist
+3. Resume from the next incomplete phase
+4. Inform the user which phases are being skipped
+
+## Progress Tracking
+
+At the start of execution, create a TodoWrite with all applicable phases. Update status as each phase completes.
+
+## Workflow
+
+### Phase 0: Context & Baseline
+
+**Role**: Software engineer preparing for refactoring
+**Goal**: Collect refactoring goals and capture baseline metrics
+**Constraints**: Measurement only — no code changes
+
+#### 0a. Collect Goals
+
+If PROBLEM_DIR files do not yet exist, help the user create them:
+
+1. `problem.md` — what the system currently does, what changes are needed, pain points
+2. `acceptance_criteria.md` — success criteria for the refactoring
+3. `security_approach.md` — security requirements (if applicable)
+
+Store in PROBLEM_DIR.
+
+#### 0b. Capture Baseline
+
+1. Read problem description and acceptance criteria
+2. Measure current system metrics using project-appropriate tools:
+
+| Metric Category | What to Capture |
+|----------------|-----------------|
+| **Coverage** | Overall, unit, integration, critical paths |
+| **Complexity** | Cyclomatic complexity (avg + top 5 functions), LOC, tech debt ratio |
+| **Code Smells** | Total, critical, major |
+| **Performance** | Response times (P50/P95/P99), CPU/memory, throughput |
+| **Dependencies** | Total count, outdated, security vulnerabilities |
+| **Build** | Build time, test execution time, deployment time |
+
+3. Create functionality inventory: all features/endpoints with status and coverage
+
+**Self-verification**:
+- [ ] All metric categories measured (or noted as N/A with reason)
+- [ ] Functionality inventory is complete
+- [ ] Measurements are reproducible
+
+**Save action**: Write `REFACTOR_DIR/baseline_metrics.md`
+
+**BLOCKING**: Present baseline summary to user. Do NOT proceed until user confirms.
+
+---
+
+### Phase 1: Discovery
+
+**Role**: Principal software architect
+**Goal**: Generate documentation from existing code and form solution description
+**Constraints**: Document what exists, not what should be. No code changes.
+
+**Skip condition** (Targeted mode): If `COMPONENTS_DIR` and `SOLUTION_DIR` already contain documentation for the target area, skip to Phase 2. Ask user to confirm skip.
+
+#### 1a. Document Components
+
+For each component in the codebase:
+
+1. Analyze project structure, directories, files
+2. Go file by file, analyze each method
+3. Analyze connections between components
+
+Write per component to `REFACTOR_DIR/discovery/components/[##]_[name].md`:
+- Purpose and architectural patterns
+- Mermaid diagrams for logic flows
+- API reference table (name, description, input, output)
+- Implementation details: algorithmic complexity, state management, dependencies
+- Caveats, edge cases, known limitations
+
+#### 1b. Synthesize Solution & Flows
+
+1. Review all generated component documentation
+2. Synthesize into a cohesive solution description
+3. Create flow diagrams showing component interactions
+
+Write:
+- `REFACTOR_DIR/discovery/solution.md` — product description, component overview, interaction diagram
+- `REFACTOR_DIR/discovery/system_flows.md` — Mermaid flowcharts per major use case
+
+Also copy to project standard locations if in project mode:
+- `SOLUTION_DIR/solution.md`
+- `COMPONENTS_DIR/system_flows.md`
+
+**Self-verification**:
+- [ ] Every component in the codebase is documented
+- [ ] Solution description covers all components
+- [ ] Flow diagrams cover all major use cases
+- [ ] Mermaid diagrams are syntactically correct
+
+**Save action**: Write discovery artifacts
+
+**BLOCKING**: Present discovery summary to user. Do NOT proceed until user confirms documentation accuracy.
+
+---
+
+### Phase 2: Analysis
+
+**Role**: Researcher and software architect
+**Goal**: Research improvements and produce a refactoring roadmap
+**Constraints**: Analysis only — no code changes
+
+#### 2a. Deep Research
+
+1. Analyze current implementation patterns
+2. Research modern approaches for similar systems
+3. Identify what could be done differently
+4. Suggest improvements based on state-of-the-art practices
+
+Write `REFACTOR_DIR/analysis/research_findings.md`:
+- Current state analysis: patterns used, strengths, weaknesses
+- Alternative approaches per component: current vs alternative, pros/cons, migration effort
+- Prioritized recommendations: quick wins + strategic improvements
+
+#### 2b. Solution Assessment
+
+1. Assess current implementation against acceptance criteria
+2. Identify weak points in codebase, map to specific code areas
+3. Perform gap analysis: acceptance criteria vs current state
+4. Prioritize changes by impact and effort
+
+Write `REFACTOR_DIR/analysis/refactoring_roadmap.md`:
+- Weak points assessment: location, description, impact, proposed solution
+- Gap analysis: what's missing, what needs improvement
+- Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
+
+**Self-verification**:
+- [ ] All acceptance criteria are addressed in gap analysis
+- [ ] Recommendations are grounded in actual code, not abstract
+- [ ] Roadmap phases are prioritized by impact
+- [ ] Quick wins are identified separately
+
+**Save action**: Write analysis artifacts
+
+**BLOCKING**: Present refactoring roadmap to user. Do NOT proceed until user confirms.
+
+**Quick Assessment mode stops here.** Present final summary and write `FINAL_report.md` with phases 0-2 content.
+
+---
+
+### Phase 3: Safety Net
+
+**Role**: QA engineer and developer
+**Goal**: Design and implement tests that capture current behavior before refactoring
+**Constraints**: Tests must all pass on the current codebase before proceeding
+
+#### 3a. Design Test Specs
+
+Coverage requirements (must meet before refactoring):
+- Minimum overall coverage: 75%
+- Critical path coverage: 90%
+- All public APIs must have integration tests
+- All error handling paths must be tested
+
+For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_name].md`:
+- Integration tests: summary, current behavior, input data, expected result, max expected time
+- Acceptance tests: summary, preconditions, steps with expected results
+- Coverage analysis: current %, target %, uncovered critical paths
+
+#### 3b. Implement Tests
+
+1. Set up test environment and infrastructure if not exists
+2. Implement each test from specs
+3. Run tests, verify all pass on current codebase
+4. Document any discovered issues
+
+**Self-verification**:
+- [ ] Coverage requirements met (75% overall, 90% critical paths)
+- [ ] All tests pass on current codebase
+- [ ] All public APIs have integration tests
+- [ ] Test data fixtures are configured
+
+**Save action**: Write test specs; implemented tests go into the project's test folder
+
+**GATE (BLOCKING)**: ALL tests must pass before proceeding to Phase 4. If tests fail, fix the tests (not the code) or ask user for guidance. Do NOT proceed to Phase 4 with failing tests.
+
+---
+
+### Phase 4: Execution
+
+**Role**: Software architect and developer
+**Goal**: Analyze coupling and execute decoupling changes
+**Constraints**: Small incremental changes; tests must stay green after every change
+
+#### 4a. Analyze Coupling
+
+1. Analyze coupling between components/modules
+2. Map dependencies (direct and transitive)
+3. Identify circular dependencies
+4. Form decoupling strategy
+
+Write `REFACTOR_DIR/coupling_analysis.md`:
+- Dependency graph (Mermaid)
+- Coupling metrics per component
+- Problem areas: components involved, coupling type, severity, impact
+- Decoupling strategy: priority order, proposed interfaces/abstractions, effort estimates
+
+**BLOCKING**: Present coupling analysis to user. Do NOT proceed until user confirms strategy.
+
+#### 4b. Execute Decoupling
+
+For each change in the decoupling strategy:
+
+1. Implement the change
+2. Run integration tests
+3. Fix any failures
+4. Commit with descriptive message
+
+Address code smells encountered: long methods, large classes, duplicate code, dead code, magic numbers.
+
+Write `REFACTOR_DIR/execution_log.md`:
+- Change description, files affected, test status per change
+- Before/after metrics comparison against baseline
+
+**Self-verification**:
+- [ ] All tests still pass after execution
+- [ ] No circular dependencies remain (or reduced per plan)
+- [ ] Code smells addressed
+- [ ] Metrics improved compared to baseline
+
+**Save action**: Write execution artifacts
+
+**BLOCKING**: Present execution summary to user. Do NOT proceed until user confirms.
+
+---
+
+### Phase 5: Hardening (Optional, Parallel Tracks)
+
+**Role**: Varies per track
+**Goal**: Address technical debt, performance, and security
+**Constraints**: Each track is optional; user picks which to run
+
+Present the three tracks and let user choose which to execute:
+
+#### Track A: Technical Debt
+
+**Role**: Technical debt analyst
+
+1. Identify and categorize debt items: design, code, test, documentation
+2. Assess each: location, description, impact, effort, interest (cost of not fixing)
+3. Prioritize: quick wins → strategic debt → tolerable debt
+4. Create actionable plan with prevention measures
+
+Write `REFACTOR_DIR/hardening/technical_debt.md`
+
+#### Track B: Performance Optimization
+
+**Role**: Performance engineer
+
+1. Profile current performance, identify bottlenecks
+2. For each bottleneck: location, symptom, root cause, impact
+3. Propose optimizations with expected improvement and risk
+4. Implement one at a time, benchmark after each change
+5. Verify tests still pass
+
+Write `REFACTOR_DIR/hardening/performance.md` with before/after benchmarks
+
+#### Track C: Security Review
+
+**Role**: Security engineer
+
+1. Review code against OWASP Top 10
+2. Verify security requirements from `security_approach.md` are met
+3. Check: authentication, authorization, input validation, output encoding, encryption, logging
+
+Write `REFACTOR_DIR/hardening/security.md`:
+- Vulnerability assessment: location, type, severity, exploit scenario, fix
+- Security controls review
+- Compliance check against `security_approach.md`
+- Recommendations: critical fixes, improvements, hardening
+
+**Self-verification** (per track):
+- [ ] All findings are grounded in actual code
+- [ ] Recommendations are actionable with effort estimates
+- [ ] All tests still pass after any changes
+
+**Save action**: Write hardening artifacts
+
+---
+
+## Final Report
+
+After all executed phases complete, write `REFACTOR_DIR/FINAL_report.md`:
+
+- Refactoring mode used and phases executed
+- Baseline metrics vs final metrics comparison
+- Changes made summary
+- Remaining items (deferred to future)
+- Lessons learned
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| Unclear refactoring scope | **ASK user** |
+| Ambiguous acceptance criteria | **ASK user** |
+| Tests failing before refactoring | **ASK user** — fix tests or fix code? |
+| Coupling change risks breaking external contracts | **ASK user** |
+| Performance optimization vs readability trade-off | **ASK user** |
+| Missing baseline metrics (no test suite, no CI) | **WARN user**, suggest building safety net first |
+| Security vulnerability found during refactoring | **WARN user** immediately, don't defer |
+
+## Trigger Conditions
+
+When the user wants to:
+- Improve existing code structure or quality
+- Reduce technical debt or coupling
+- Prepare codebase for new features
+- Assess code health before major changes
+
+**Keywords**: "refactor", "refactoring", "improve code", "reduce coupling", "technical debt", "code quality", "decoupling"
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│           Structured Refactoring (6-Phase Method)              │
+├────────────────────────────────────────────────────────────────┤
+│ CONTEXT: Resolve mode (project vs standalone) + set paths      │
+│ MODE: Full / Targeted / Quick Assessment                       │
+│                                                                │
+│ 0. Context & Baseline  → baseline_metrics.md                   │
+│    [BLOCKING: user confirms baseline]                          │
+│ 1. Discovery           → discovery/ (components, solution)     │
+│    [BLOCKING: user confirms documentation]                     │
+│ 2. Analysis            → analysis/ (research, roadmap)         │
+│    [BLOCKING: user confirms roadmap]                           │
+│    ── Quick Assessment stops here ──                           │
+│ 3. Safety Net          → test_specs/ + implemented tests       │
+│    [GATE: all tests must pass]                                 │
+│ 4. Execution           → coupling_analysis, execution_log      │
+│    [BLOCKING: user confirms changes]                           │
+│ 5. Hardening           → hardening/ (debt, perf, security)     │
+│    [optional, user picks tracks]                               │
+│    ─────────────────────────────────────────────────           │
+│    FINAL_report.md                                             │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Preserve behavior · Measure before/after           │
+│             Small changes · Save immediately · Ask don't assume│
+└────────────────────────────────────────────────────────────────┘
+```