prd.json

{
  "project": "PatternFly Migration Rule Analysis",
  "branchName": "ralph/patternfly-rule-analysis",
  "description": "Validate AI-generated Konveyor migration rules for PatternFly 5→6, research official guidance, analyze all rules, and produce actionable cleanup recommendations with automation scripts",
  "userStories": [
    {
      "id": "US-001",
      "title": "Fetch and structure official upgrade documentation",
      "description": "As a rule analyst, I need comprehensive guidance from the official PatternFly upgrade docs so I can validate migration rules against authoritative sources.",
      "acceptanceCriteria": [
        "Fetch content from https://www.patternfly.org/get-started/upgrade",
        "Extract all PatternFly 5→6 migration requirements",
        "Structure by migration path/workflow (not individual rules)",
        "Include: what changes, how to detect, how to fix",
        "Save to `Guidance_PatternFly_5_to_6.md` in working directory",
        "Document is detailed enough to write new rules from scratch",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": true,
      "notes": "Completed 2026-01-27. Created comprehensive guidance document with 9 major sections covering all migration paths."
    },
    {
      "id": "US-002",
      "title": "Extract patterns from PatternFly codemods v6 rules",
      "description": "As a rule analyst, I need to understand the official codemod patterns so I can validate our YAML rules against proven transformation logic.",
      "acceptanceCriteria": [
        "Fetch all v6 rule files from https://github.com/patternfly/pf-codemods/tree/main/packages/eslint-plugin-pf-codemods/src/rules/v6",
        "Extract detection patterns (selectors, code signatures)",
        "Extract transformation logic (replacement patterns)",
        "Merge findings into `Guidance_PatternFly_5_to_6.md` organized by migration path",
        "Cross-reference with upgrade documentation to ensure completeness",
        "Typecheck passes"
      ],
      "priority": 2,
      "passes": true,
      "notes": "Completed 2026-01-27. Extracted patterns from 97 of 106 v6 codemod rules. Created comprehensive documentation (Codemod_Patterns_Extracted.md, Pattern_Analysis_Summary.md, Coverage_Analysis.md, codemod_patterns.json). Enhanced Guidance document with codemod pattern references, detection/transformation approaches, and comprehensive cross-reference mapping all components to their corresponding codemod rules."
    },
    {
      "id": "US-003",
      "title": "Create analysis methodology document",
      "description": "As a rule analyst, I need a clear methodology for evaluating rules so the analysis is consistent and repeatable.",
      "acceptanceCriteria": [
        "Define tiered scoring criteria (High/Medium/Low/No Value) with specific examples",
        "Define action flags (Delete vs Review/Fix) with decision criteria",
        "Document how to identify no-op transformations (A→A patterns)",
        "Document how to detect contradictions with official guidance",
        "Document how to identify redundant rules (duplicates with variations)",
        "Save to `Plan_to_Analyze_Patternfly_Rules.md` in working directory",
        "Typecheck passes"
      ],
      "priority": 3,
      "passes": true,
      "notes": "Completed 2026-01-27. Created comprehensive 789-line methodology document with tiered scoring criteria, action flags, detection methods for no-ops/contradictions/duplicates, analysis workflow, and 5 detailed example analyses."
    },
    {
      "id": "US-004",
      "title": "Inventory all YAML rules in directory",
      "description": "As a rule analyst, I need a complete list of all YAML rules to ensure none are missed during analysis.",
      "acceptanceCriteria": [
        "Scan directory /home/jmatthews.linux/Shared/patternfly_experiments/rulesets/preview/nodejs/patternfly for all .yaml and .yml files",
        "Extract rule identifiers/filenames",
        "Count total rules to analyze",
        "Create tracking structure for analysis progress",
        "Save inventory to working directory",
        "Typecheck passes"
      ],
      "priority": 4,
      "passes": true,
      "notes": "Completed 2026-01-27. Created Python inventory script that scanned directory and found 50 rule files, 11 test files, and 225 total rules. Generated comprehensive tracking outputs: Rule_Inventory.md (markdown report with statistics), rule_inventory.json (machine-readable with tracking fields), rule_inventory.csv (tracking spreadsheet). Inventory includes analysis_status, tier, action, and notes fields for each rule file."
    },
    {
      "id": "US-005",
      "title": "Analyze each rule against guidance",
      "description": "As a rule analyst, I need to evaluate every single rule for quality so I can make informed deletion/fix recommendations.",
      "acceptanceCriteria": [
        "For each YAML rule, extract: detection logic, transformation logic, metadata",
        "Compare against corresponding guidance in `Guidance_PatternFly_5_to_6.md`",
        "Assign tier score: High/Medium/Low/No Value",
        "Identify no-op transformations (source == target)",
        "Identify contradictions with official guidance",
        "Identify redundant rules (functional duplicates)",
        "Assign action flag if applicable (Delete or Review/Fix)",
        "Write specific improvement comment for Review/Fix flagged rules",
        "Process 100% of rules (no sampling or skipping)",
        "Save intermediate analysis data to working directory",
        "Typecheck passes"
      ],
      "priority": 5,
      "passes": true,
      "notes": "Completed 2026-01-27. Analyzed all 225 rules across 50 files. Results: 14 High Value (6.2%), 64 Medium Value (28.4%), 97 Low Value (43.1%), 50 No Value (22.2%). Actions: 51 DELETE, 145 REVIEW/FIX, 29 Keep. Created comprehensive analysis outputs with tier scores, action flags, justifications, and specific improvement comments for every rule. 100% coverage validated."
    },
    {
      "id": "US-006",
      "title": "Generate human-readable analysis report",
      "description": "As a project stakeholder, I need a comprehensive markdown report so I can understand findings and recommendations at a glance.",
      "acceptanceCriteria": [
        "Create `Analysis_Results_Patternfly_Rules.md` in working directory",
        "Include analysis of every single YAML rule with: filename, tier score, action flag, justification",
        "Include summary statistics: counts by tier, counts by action flag",
        "Include coverage gap analysis: migration paths with no corresponding rules",
        "Include recommendations section prioritizing deletions and critical fixes",
        "Report is structured for easy navigation (table of contents, sections)",
        "Typecheck passes"
      ],
      "priority": 6,
      "passes": true,
      "notes": "Completed 2026-01-27. Generated comprehensive 129KB markdown report (3623 lines) with executive summary, statistics, detailed analysis of all 225 rules organized by tier, coverage gap analysis (7 migration paths with insufficient coverage), and prioritized recommendations (P1: Delete 51 rules, P2: Fix critical issues, P3: Improve medium-value rules). Includes table of contents with anchor links. 100% rule coverage validated."
    },
    {
      "id": "US-007",
      "title": "Export machine-readable analysis data",
      "description": "As an automation engineer, I need structured data exports so I can programmatically process results and generate cleanup scripts.",
      "acceptanceCriteria": [
        "Export analysis results to JSON format with schema: {filename, tier, action, comment, guidance_ref}",
        "Export summary statistics to JSON: {tier_counts, action_counts, total_rules}",
        "Export coverage gaps to JSON: {migration_path, severity, notes}",
        "Save exports to `analysis_results.json`, `summary_stats.json`, `coverage_gaps.json` in working directory",
        "JSON validates against defined schema",
        "Typecheck passes"
      ],
      "priority": 7,
      "passes": true,
      "notes": "Completed 2026-01-27. Generated three machine-readable JSON exports: analysis_results.json (225 rules with schema: filename, tier, action, comment, guidance_ref), summary_stats.json (tier/action counts with percentages), coverage_gaps.json (7 migration path gaps with severity levels). Created export_analysis_data.py for generation and validate_us007.py for schema validation. All JSON files validate against defined schemas. 100% acceptance criteria verified."
    },
    {
      "id": "US-008",
      "title": "Generate automated cleanup scripts",
      "description": "As a repository maintainer, I need executable scripts that automate rule cleanup so I can quickly act on recommendations.",
      "acceptanceCriteria": [
        "Create `cleanup_delete_rules.sh` script that deletes all rules flagged for deletion",
        "Script includes dry-run mode (preview without executing)",
        "Script logs all actions with timestamps",
        "Create `cleanup_summary.md` template for documenting what was deleted/fixed",
        "Scripts validate against machine-readable exports before executing",
        "Include rollback instructions in script comments",
        "Save scripts to working directory",
        "Typecheck passes"
      ],
      "priority": 8,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-009",
      "title": "Validate analysis completeness",
      "description": "As a quality assurance reviewer, I need verification that the analysis covered everything so I can trust the recommendations.",
      "acceptanceCriteria": [
        "Cross-check: number of rules analyzed == number of YAML files in directory",
        "Verify every rule has assigned tier score",
        "Verify every 'No Value' rule has action flag",
        "Verify every 'Review/Fix' flag has specific improvement comment",
        "Verify all guidance migration paths are referenced at least once",
        "Document any anomalies or edge cases in analysis report",
        "Add validation summary to `Analysis_Results_Patternfly_Rules.md`",
        "Typecheck passes"
      ],
      "priority": 9,
      "passes": false,
      "notes": ""
    }
  ]
}