x-ipe-docs/planning/project-quality-evaluation.md

QualityEvaluation:
  # Metadata
  evaluation_id: QE-{YYYYMMDD}-{sequence}
  generated_at: <ISO timestamp>
  generated_by: <agent nickname>
  scope: project | feature | module
  
  # Summary Metrics
  overall_score: <1-10>
  health_status: healthy | attention_needed | critical
  
  # Feature-Level Evaluations
  features:
    - feature_id: FEATURE-XXX
      feature_name: "<name>"
      status: aligned | needs_attention | critical | planned | not_evaluated
      
      requirements_alignment:
        status: aligned | needs_update | not_found | planned
        requirement_docs: [<paths>]
        gaps:
          - type: undocumented | unimplemented | deviated
            description: "<gap description>"
            severity: high | medium | low
      
      specification_alignment:
        status: aligned | needs_update | not_found | planned
        spec_doc: "<path>"
        gaps:
          - type: missing | outdated | incorrect
            description: "<gap description>"
            severity: high | medium | low
      
      test_coverage:
        status: sufficient | insufficient | no_tests
        line_coverage: <XX%>
        branch_coverage: <XX%>
        critical_untested:
          - area: "<untested area>"
            risk: high | medium | low
      
      code_alignment:
        status: aligned | drifted | major_drift
        implementation_files: [<paths>]
        gaps:
          - type: structure | behavior | interface
            description: "<gap description>"
            severity: high | medium | low
  
  # Aggregated Gaps
  priority_gaps:
    high: [<gap references>]
    medium: [<gap references>]
    low: [<gap references>]
  
  # Refactoring Suggestions (from task-type-refactoring-analysis)
  refactoring_suggestions:
    has_suggestions: true | false
    source: "<evaluation_id or task_id that generated suggestions>"
    
    suggestions:
      - feature_id: FEATURE-XXX
        summary: "<high-level description>"
        goals:
          - goal: "<specific improvement goal>"
            priority: high | medium | low
            rationale: "<why this goal matters>"
        target_structure: "<description of desired structure>"
        
        principles:
          primary:
            - principle: <SOLID | DRY | KISS | YAGNI | SoC | etc.>
              rationale: "<why this principle applies>"
              applications:
                - area: "<code area>"
                  action: "<specific application>"
          secondary:
            - principle: <name>
              rationale: "<supporting rationale>"
          constraints:
            - constraint: "<what to avoid or preserve>"
              reason: "<why>"
  
  # Recommendations
  recommendations:
    - priority: <1-N>
      category: requirements | specification | testing | code | refactoring
      action: "<recommended action>"
      affected_features: [<feature_ids>]

1. DETERMINE scope:
   - Default: all features in project
   - If feature_ids provided: filter to those features
   - If module_paths provided: find features affecting those modules

2. DISCOVER features:
   FOR project scope:
     - SCAN x-ipe-docs/requirements/FEATURE-* directories
     - BUILD feature list with metadata
   
3. FOR EACH feature:
   a. EVALUATE requirements alignment (see Evaluation Procedures)
   b. EVALUATE specification alignment
   c. EVALUATE test coverage
   d. EVALUATE code alignment
   e. COLLECT violations per category (requirements, spec, test, code)
   f. CALCULATE feature status and score

4. AGGREGATE results:
   - Calculate overall_score (weighted average, exclude planned features)
   - Determine health_status
   - Collect priority_gaps
   - Generate recommendations

5. GENERATE report following this structure:
   a. Executive Summary (scores, key findings)
   b. Evaluation Principles (thresholds/methods ONLY - no results)
   c. Feature-by-Feature Evaluation (overview table)
   d. Violation Details by Feature:
      - FOR EACH feature with violations:
        - Requirements Violations section
        - Specification Violations section
        - Test Coverage Violations section
        - Code Alignment Violations section
   e. Files Approaching Threshold
   f. Priority Gaps Summary
   g. Recommendations
   h. Appendix (detailed metrics)

6. SAVE report:
   - Save to x-ipe-docs/planning/project-quality-evaluation.md
   - Update version and evaluated date in header

7. RETURN evaluation summary

RULE 1: Evaluation Principles section
  - MUST come BEFORE Feature-by-Feature Evaluation
  - MUST only explain what principles are and thresholds
  - MUST NOT contain any evaluation results or status

RULE 2: Violation Details section
  - MUST be organized by feature
  - EACH feature section MUST have 4 subsections:
    - Requirements Violations
    - Specification Violations
    - Test Coverage Violations
    - Code Alignment Violations
  - ONLY show features that have violations
  - Show "No violations" if a category is clean

RULE 3: Separation of concerns
  - Principles = WHAT we evaluate and HOW (thresholds)
  - Violations = RESULTS of evaluation per feature

1. LOAD latest report from quality-evaluation-latest.md
2. FOR EACH feature_id:
   - RE-EVALUATE all 4 perspectives
   - UPDATE feature entry in report
3. RE-CALCULATE aggregates (overall_score, health_status)
4. UPDATE priority_gaps and recommendations
5. SAVE as new timestamped report
6. UPDATE quality-evaluation-latest.md

1. LOAD latest report
2. FILTER features by criteria
3. RETURN filtered evaluation data

1. LOAD both evaluation reports
2. FOR EACH feature in both:
   - COMPARE status changes
   - CALCULATE score deltas
   - IDENTIFY new/resolved gaps
3. GENERATE comparison summary:
   - Improved features
   - Degraded features
   - New gaps introduced
   - Gaps resolved
4. RETURN comparison data

1. LOCATE requirement docs:
   - x-ipe-docs/requirements/requirement-summary.md
   - x-ipe-docs/requirements/requirement-details.md
   - Any docs referencing feature

2. FOR EACH requirement related to feature:
   a. CHECK if requirement is documented
   b. CHECK if requirement is implemented in code
   c. IDENTIFY deviations between doc and implementation

3. CLASSIFY gaps:
   - undocumented: Implemented but not in requirements
   - unimplemented: In requirements but not implemented
   - deviated: Implementation differs from requirement

4. ASSIGN severity:
   - high: Core functionality affected
   - medium: Secondary functionality affected
   - low: Minor/edge cases

1. LOCATE specification:
   - x-ipe-docs/requirements/FEATURE-XXX/specification.md

2. IF specification exists:
   a. EXTRACT expected behaviors
   b. COMPARE with actual implementation
   c. IDENTIFY gaps (missing | outdated | incorrect)
   
3. IF specification missing (empty feature folder):
   a. CHECK if any related implementation exists in codebase
   b. IF no implementation found:
      - status: planned
      - NOT a gap - just indicates future work needed
      - Do NOT count as critical or high priority gap
   c. IF implementation exists without specification:
      - status: not_found
      - Add gap: "Implementation exists but specification missing"
      - severity: medium (documentation debt)

1. IDENTIFY test files for feature:
   - tests/**/test_*{feature_name}*
   - tests/**/*{feature_name}*_test.*

2. RUN coverage analysis:
   - Python: pytest --cov
   - Node.js: npm test -- --coverage
   - Go: go test -cover

3. EXTRACT metrics:
   - Line coverage %
   - Branch coverage %
   - Untested functions/areas

4. IDENTIFY critical untested areas:
   - Business logic paths
   - Error handlers
   - Edge cases

5. DETERMINE status:
   - sufficient: ≥80% line coverage, no critical gaps
   - insufficient: <80% or has critical gaps
   - no_tests: No test files found

1. LOCATE technical design:
   - x-ipe-docs/requirements/FEATURE-XXX/technical-design.md

2. IF technical design exists:
   a. EXTRACT expected:
      - File structure
      - Component interfaces
      - Data models
   b. COMPARE with actual implementation
   c. IDENTIFY gaps:
      - structure: File/folder organization differs
      - behavior: Logic differs from design
      - interface: API/interface differs

3. DETERMINE status:
   - aligned: No significant gaps
   - drifted: Minor gaps exist
   - major_drift: Critical gaps exist

1. ANALYZE gaps from all 4 perspectives:
   - Collect all gaps with severity high/medium
   - Group gaps by feature

2. FOR EACH feature with gaps:
   a. IDENTIFY applicable principles (from task-type-refactoring-analysis):
      - Large files/classes → SRP, SOLID
      - Duplicated code → DRY
      - Complex logic → KISS
      - Unused code → YAGNI
      - Mixed concerns → SoC (Separation of Concerns)
   
   b. FORMULATE goals based on gaps:
      - requirements gaps → Suggest documentation sync or code alignment
      - specification gaps → Suggest spec update or implementation fix
      - test coverage gaps → Suggest test-first approach
      - code alignment gaps → Suggest structural refactoring
   
   c. DEFINE target structure:
      - Describe desired code organization after fixes
      - Note key structural changes needed
   
   d. IDENTIFY constraints:
      - Backward compatibility requirements
      - API stability requirements
      - Dependencies to preserve

3. COMPILE refactoring_suggestion for feature:
   summary: "<derived from gap analysis>"
   goals:
     - goal: "<specific goal from gap>"
       priority: <based on gap severity>
       rationale: "<from gap description>"
   target_structure: "<desired end state>"
   
   principles:
     primary: [<principles with applications>]
     secondary: [<supporting principles>]
     constraints: [<identified constraints>]

4. IF no gaps found for feature:
   - Set has_suggestions: false for that feature
   - Skip suggestion generation

feature_score = weighted_average(
  requirements_alignment: weight=0.25,
  specification_alignment: weight=0.25,
  test_coverage: weight=0.25,
  code_alignment: weight=0.25
)

Status to score mapping:
- aligned/sufficient: 10
- planned: N/A (exclude from scoring - future work)
- needs_update/insufficient: 5
- not_found/no_tests/major_drift: 2
- critical: 1

Note: Features with status "planned" (empty folder, no implementation) 
are EXCLUDED from overall score calculation as they represent future 
work, not quality issues.

overall_score = average(all feature_scores WHERE status != "planned")

IF overall_score >= 8: healthy
ELSE IF overall_score >= 5: attention_needed
ELSE: critical

1. Generate full project evaluation
2. Set baseline metrics
3. Create recommendations for initial improvements
4. Flag features needing immediate attention

1. Load code_quality_evaluated from refactoring task
2. Use as input for targeted re-evaluation
3. Compare with pre-refactoring state
4. Generate delta report showing improvements

Quality Report (baseline)
    ↓
task-type-refactoring-analysis
    ↓
task-type-improve-code-quality-before-refactoring
    ↓
Quality Report (mid-point)
    ↓
task-type-code-refactor-v2
    ↓
Quality Report (final) + Comparison