按阶段对整个代码库做系统排查，找出、排序、修复并记录缺陷和安全漏洞，适合代码审计。
{
"task": "comprehensive_repository_analysis",
"objective": "对整个代码库进行彻底分析，以识别、优先处理、修复和记录任何技术栈中存在的所有可验证的缺陷、安全漏洞和关键问题",
"analysis_phases": [
{
"phase": 1,
"name": "仓库发现与映射",
"steps": [
{
"step": "1.1",
"title": "架构与结构分析",
"actions": [
"映射完整的目录结构（src/, lib/, tests/, docs/, config/, scripts/, build/, deploy/）",
"识别所有正在使用的技术栈和框架",
"解析依赖清单文件（package.json, requirements.txt, go.mod, pom.xml, Gemfile, Cargo.toml, composer.json）",
"记录入口点、主执行路径和模块边界",
"分析构建系统（Webpack, Gradle, Maven, Make, CMake）",
"审查 CI/CD 配置（GitHub Actions, GitLab CI, Jenkins, CircleCI）",
"检查现有文档（README, CONTRIBUTING, API 规范, 架构图）"
]
},
{
"step": "1.2",
"title": "开发环境清查",
"actions": [
"识别测试框架（Jest, Mocha, pytest, PHPUnit, Go test, JUnit, RSpec, xUnit）",
"审查 linter/formatter 配置（ESLint, Prettier, Black, Flake8, RuboCop, golangci-lint, Checkstyle）",
"扫描内联问题标记（TODO, FIXME, HACK, XXX, BUG, NOTE）",
"分析 git 历史记录中的问题模式和近期热修复",
"提取现有的测试覆盖率报告和指标",
"识别已在使用的代码分析工具（SonarQube, CodeClimate 等）"
]
}
]
},
{
"phase": 2,
"name": "系统性缺陷发现",
"bug_categories": [
{
"category": "CRITICAL",
"severity": "P0",
"types": [
"SQL 注入漏洞",
"跨站脚本（XSS）缺陷",
"跨站请求伪造（CSRF）漏洞",
"认证/授权绕过",
"远程代码执行（RCE）风险",
"数据损坏或永久性数据丢失",
"系统崩溃、死锁或无限循环",
"内存泄漏和资源耗尽",
"不安全的加密实现",
"硬编码的密钥或凭据"
]
},
{
"category": "FUNCTIONAL",
"severity": "P1-P2",
"types": [
"逻辑错误（条件判断错误、计算错误、差一错误）",
"状态管理问题（竞态条件、陈旧状态、不正确的状态变更）",
"不正确的 API 合约或请求/响应映射",
"缺少或不足的输入验证",
"损坏的业务逻辑或流程违规",
"不正确的数据转换或序列化",
"类型不匹配或不安全的类型强制转换",
"不正确的异常处理或错误传播"
]
},
{
"category": "INTEGRATION",
"severity": "P2",
"types": [
"不正确的外部 API 使用或已过时的端点",
"数据库查询错误、SQL 语法问题或 N+1 问题",
"消息队列处理失败（RabbitMQ, Kafka, SQS）",
"文件系统操作错误（权限、路径遍历）",
"网络通信问题（超时、重试、连接池）",
"缓存不一致或失效问题",
"第三方库误用或版本不兼容"
]
},
{
"category": "EDGE_CASES",
"severity": "P2-P3",
"types": [
"空指针解引用（null/undefined/nil/None）",
"空数组/列表/集合的处理",
"零值或负值的边界情况",
"边界条件（整数最大/最小值、字符串长度限制）",
"缺少错误处理或被吞掉的异常",
"超时和重试逻辑失败",
"并发访问时缺乏正确锁机制",
"数值运算中的溢出/下溢"
]
},
{
"category": "CODE_QUALITY",
"severity": "P3-P4",
"types": [
"已弃用 API 的使用",
"无效代码或不可达代码路径",
"循环依赖",
"性能瓶颈（低效算法、冗余操作）",
"缺少或不正确的类型注解",
"不一致的错误处理模式",
"资源泄漏（文件句柄、数据库连接、网络套接字）"
{
"phase": 3,
"name": "缺陷记录与优先级排序",
"bug_report_schema": {
"bug_id": "顺序标识符（BUG-001、BUG-002 等）",
"severity": {
"type": "enum",
"values": [
"CRITICAL",
"HIGH",
"MEDIUM",
"LOW"
],
"description": "缺陷严重程度等级"
},
"category": {
"type": "enum",
"values": [
"SECURITY",
"FUNCTIONAL",
"PERFORMANCE",
"INTEGRATION",
"CODE_QUALITY"
],
"description": "缺陷分类"
},
"location": {
"files": [
"受影响文件路径及其行号的数组"
],
"component": "模块/服务/功能名称",
"function": "具体函数或方法名称"
},
"description": {
"current_behavior": "当前存在问题或错误的行为",
"expected_behavior": "预期应发生的行为",
"root_cause": "问题技术成因的解释"
},
"impact_assessment": {
"user_impact": "对终端用户的影响（数据丢失、安全暴露、用户体验下降）",
"system_impact": "对系统的影响（性能、稳定性、可扩展性）",
"business_impact": "对业务的影响（合规性、收入、声誉、法律）"
},
"reproduction": {
"steps": [
"复现问题的逐步操作说明"
],
"test_data": "所需样本数据或条件",
"actual_result": "复现时实际发生的结果",
"expected_result": "预期应发生的结果"
},
"verification": {
"code_snippet": "展示该缺陷的代码示例",
"test_case": "因该缺陷而失败的测试用例",
"logs_or_metrics": "来自日志或监控的证据"
},
"dependencies": {
"related_bugs": [
"相关 BUG-ID 的数组"
],
"blocking_issues": [
"必须先修复的缺陷数组"
],
"blocked_by": [
"阻碍修复的外部因素"
]
},
"metadata": {
"discovered_date": "ISO 8601 时间戳",
"discovered_by": "使用的工具或方法",
"cve_id": "如适用，CVE 标识符",
"cwe_id": "如适用，CWE 标识符"
}
},
"prioritization_matrix": {
"criteria": [
{
"factor": "severity",
"weight": 0.4,
"scale": "CRITICAL=100, HIGH=70, MEDIUM=40, LOW=10"
},
{
"factor": "user_impact",
"weight": 0.3,
"scale": "All users=100, Many=70, Some=40, Few=10"
},
{
"factor": "fix_complexity",
"weight": 0.15,
"scale": "Simple=100, Medium=60, Complex=20"
},
{
"factor": "regression_risk",
"weight": 0.15,
"scale": "Low=100, Medium=60, High=20"
}
],
"formula": "priority_score = Σ(factor_value × weight)"
}
},
{
"phase": 4,
"name": "修复实施",
"fix_workflow": [
{
"step": 1,
"action": "创建独立的修复分支",
"naming": "fix/BUG-{id}-{short-description}"
},
{
"step": 2,
"action": "首先编写失败测试",
"rationale": "测试驱动开发确保修复可验证"
},
{
"step": 3,
"action": "实施最小化、聚焦的修复",
"principle": "能正确解决问题的最小变更"
},
{
"step": 4,
"action": "验证测试现在通过",
"validation": "运行特定测试及相关测试套件"
},
{
"step": 5,
"action": "运行完整的回归测试套件",
"validation": "确保现有功能未被破坏"
},
{
"step": 6,
"action": "更新文档",
"scope": "API 文档、内联注释、变更日志"
}
],
"fix_principles": [
"MINIMAL_CHANGE: 做出能正确修复问题的最小改动",
"NO_SCOPE_CREEP: 避免无关的重构或功能添加",
"BACKWARDS_COMPATIBLE: 除非问题本身是破坏性变更，否则保留现有 API 合约",
"FOLLOW_CONVENTIONS: 遵循项目现有的代码风格和模式",
"DEFENSIVE_PROGRAMMING: 添加防护措施以防止未来出现类似错误",
"EXPLICIT_OVER_IMPLICIT: 通过代码结构和注释明确表达意图",
"FAIL_FAST: 提前验证输入，并以清晰的错误消息快速失败"
],
"code_review_checklist": [
"修复解决了根本原因，而不仅仅是表面症状",
"所有边界情况都得到了妥善处理",
"错误消息清晰、可操作，且不暴露敏感信息",
"性能影响可接受（不应使用 O(n²) 而 O(n) 即可满足需求）",
"已充分考虑安全影响",
"未引入新的编译器警告或代码检查错误",
"变更已被测试覆盖",
"文档已更新且准确",
"破坏性变更已明确标注并说明理由",
"依赖项已更新至最新且安全版本"
]
},
{
"phase": 5,
"name": "测试与验证",
"test_requirements": {
"mandatory_tests_per_fix": [
{
"type": "unit_test",
"description": "针对特定缺陷修复的独立测试",
"coverage": "必须覆盖被破坏的确切代码路径"
},
{
"type": "integration_test",
"description": "如果缺陷涉及多个组件，则进行测试",
"coverage": "贯穿受影响系统的端到端流程"
},
{
"type": "regression_test",
"description": "确保修复不会破坏现有功能",
"coverage": "所有相关特性和代码路径"
},
{
"type": "edge_case_tests",
"description": "覆盖边界条件和极端情况",
"coverage": "空值、空输入、极限值、错误条件"
}
]
},
"test_structure_template": {
"description": "语言无关的测试结构",
"template": [
"describe('BUG-{ID}: {description}', () => {",
" test('reproduces original bug', () => {",
" // 此测试证明缺陷确实存在",
" // 修复前应失败，修复后应通过",
" });",
"",
" test('verifies fix resolves issue', () => {",
" // 此测试验证修复后行为正确",
" });",
"",
" test('handles edge case: {case}', () => {",
" // 对相关场景的额外覆盖",
" });",
"});"
]
},
"validation_steps": [
{
"step": "运行完整测试套件",
"commands": {
"javascript": "npm test",
"python": "pytest",
"go": "go test ./...",
"java": "mvn test",
"ruby": "bundle exec rspec",
"rust": "cargo test",
"php": "phpunit"
}
},
{
"step": "测量代码覆盖率",
"tools": [
"Istanbul/NYC",
"Coverage.py",
"JaCoCo",
"SimpleCov",
"Tarpaulin"
]
},
{
"step": "运行静态分析",
"tools": [
"ESLint",
"Pylint",
"golangci-lint",
"SpotBugs",
"Clippy"
]
},
{
"step": "性能基准测试",
"condition": "如果修复影响热点路径或关键操作"
},
{
"step": "安全扫描",
"tools": [
"Snyk",
"OWASP Dependency-Check",
"Trivy",
"Bandit"
]
}
]
},
{
"phase": 6,
"name": "文档与报告",
"fix_documentation_requirements": [
"更新内联代码注释，解释修复内容及其必要性",
"如果行为发生变化，修订 API 文档",
"在 CHANGELOG.md 中添加缺陷修复条目",
"创建或更新故障排除指南",
"记录延迟修复/未修复问题的任何变通方案",
"如果修复需要用户操作，添加迁移说明"
],
"executive_summary_template": {
"title": "缺陷修复报告 - {repository_name}",
"metadata": {
"date": "ISO 8601 日期",
"analyzer": "工具/人员名称",
"repository": "完整仓库路径",
"commit_hash": "Git 提交 SHA",
"duration": "分析耗时（小时）"
},
"overview": {
"total_bugs_found": "整数",
"total_bugs_fixed": "整数",
"bugs_deferred": "整数"
"test_coverage_before": "百分比",
"test_coverage_after": "百分比",
"files_analyzed": "整数",
"lines_of_code": "整数"
},
"critical_findings": [
"发现的 3-5 个最关键的缺陷及其修复方案"
],
"fix_summary_by_category": {
"security": "数量",
"functional": "数量",
"performance": "数量",
"integration": "数量",
"code_quality": "数量"
},
"detailed_fix_table": {
"columns": [
"BUG-ID",
"File",
"Line",
"Category",
"Severity",
"Description",
"Status",
"Test Added"
],
"format": "Markdown 表格或 CSV"
},
"risk_assessment": {
"remaining_high_priority": [
"未修复的关键问题列表"
],
"recommended_next_steps": [
"优先级排序的行动项"
],
"technical_debt": [
"已识别技术债务的摘要"
],
"breaking_changes": [
"任何向后不兼容的修复"
]
},
"testing_results": {
"test_command": "用于运行测试的确切命令",
"tests_passed": "X / Y",
"tests_failed": "数量及失败原因",
"tests_added": "数量",
"coverage_delta": "+X% 或 -X%"
}
},
"deliverables_checklist": [
"所有缺陷以标准化格式记录",
"修复以最小影响范围实施",
"测试套件已更新并通过",
"文档已更新（代码、API、用户指南）",
"代码审查已完成并获批准",
"性能影响已评估且可接受",
"针对安全相关修复进行了安全审查",
"已准备部署说明和回滚计划",
"变更日志已更新，包含面向用户的变化",
"已通知相关方关键修复"
]
},
{
"phase": 7,
"name": "持续改进",
"pattern_analysis": {
"objectives": [
"识别代码库中重复出现的缺陷模式",
"检测导致缺陷的架构问题",
"发现测试策略中的盲区",
"突出存在技术债务的区域"
],
"outputs": [
"常见缺陷模式报告",
"预防措施建议",
"工具改进建议",
"架构重构提案"
]
},
"monitoring_recommendations": {
"metrics_to_track": [
"随时间变化的缺陷发现率",
"按严重性划分的修复耗时",
"回归率（缺陷重新引入）",
"测试覆盖率百分比",
"易出错区域的代码变更频率",
"依赖项中的漏洞数量"
],
"alerting_rules": [
"依赖项中的关键安全漏洞",
"测试套件失败",
"测试覆盖率低于阈值",
"关键操作的性能下降"
],
"logging_improvements": [
"在缺失处添加结构化日志",
"包含用于请求追踪的关联 ID（correlation IDs）",
"记录安全相关事件",
"确保错误日志包含堆栈跟踪和上下文"
]
}
}
],
"constraints_and_best_practices": [
"绝不为简化或便利而牺牲安全性",
"维护所有变更的完整审计轨迹",
"若修复更改了公共 API，则遵循语义化版本控制",
"测试外部服务时遵守速率限制",
"对高风险或渐进式上线的修复使用功能开关（feature flags）",
"记录分析过程中做出的所有假设",
"为每项修复考虑回滚策略",
"尽可能优先选择向后兼容的修复",
"在没有合理理由的情况下避免引入新依赖",
"在适用时于多个环境中测试"
],
"output_formats": [
{
"format": "markdown",
"purpose": "供人类阅读的文档和报告",
"filename_pattern": "bug_report_{date}.md"
},
{
"format": "json",
"purpose": "供自动化处理的机器可读格式",
"filename_pattern": "bug_data_{date}.json",
"schema": "遵循第 3 阶段中定义的 bug_report_schema"
},
{
"format": "csv",
"purpose": "导入缺陷跟踪系统（Jira, GitHub Issues）",
"filename_pattern": "bugs_{date}.csv",
"columns": [
"BUG-ID",
"Severity",
"Category",
"File",
"Line",
"Description",
"Status"
]
},
{
"format": "yaml",
"purpose": "适用于 CI/CD 集成的配置友好格式",
"filename_pattern": "bug_config_{date}.yaml"
}
],
"special_considerations": {
"monorepos": "分别分析每个包/工作区，并跟踪跨包依赖关系",
"microservices": "考虑服务间契约、API 兼容性以及分布式追踪",
"legacy_code": "权衡修复的风险与收益；优先处理高影响、低风险的修复",
"third_party_dependencies": "向上游报告漏洞；若依赖项已不再维护，考虑替代方案",
"high_traffic_systems": "为修复考虑部署策略（蓝绿部署、灰度发布）",
"regulated_industries": "确保满足合规要求（HIPAA, PCI-DSS, SOC2, GDPR）",
"open_source_projects": "遵守贡献指南；在进行重大变更前与维护者沟通"
},
"success_criteria": {
"quantitative": [
"所有 CRITICAL 和 HIGH 严重级别的缺陷已解决",
"测试覆盖率至少提高 X%",
"依赖项中无安全漏洞",
"所有测试通过",
"代码质量指标提升（圈复杂度、可维护性指数）"
],
"qualitative": [
"代码库更易于维护",
"文档清晰且全面",
"团队能够自信地部署修复",
"已建立预防未来缺陷的机制",
"开发速度提升"
]
}
}{
"task": "comprehensive_repository_analysis",
"objective": "Conduct exhaustive analysis of entire codebase to identify, prioritize, fix, and document ALL verifiable bugs, security vulnerabilities, and critical issues across any technology stack",
"analysis_phases": [
{
"phase": 1,
"name": "Repository Discovery & Mapping",
"steps": [
{
"step": "1.1",
"title": "Architecture & Structure Analysis",
"actions": [
"Map complete directory structure (src/, lib/, tests/, docs/, config/, scripts/, build/, deploy/)",
"Identify all technology stacks and frameworks in use",
"Parse dependency manifests (package.json, requirements.txt, go.mod, pom.xml, Gemfile, Cargo.toml, composer.json)",
"Document entry points, main execution paths, and module boundaries",
"Analyze build systems (Webpack, Gradle, Maven, Make, CMake)",
"Review CI/CD configurations (GitHub Actions, GitLab CI, Jenkins, CircleCI)",
"Examine existing documentation (README, CONTRIBUTING, API specs, architecture diagrams)"
]
},
{
"step": "1.2",
"title": "Development Environment Inventory",
"actions": [
"Identify testing frameworks (Jest, Mocha, pytest, PHPUnit, Go test, JUnit, RSpec, xUnit)",
"Review linter/formatter configs (ESLint, Prettier, Black, Flake8, RuboCop, golangci-lint, Checkstyle)",
"Scan for inline issue markers (TODO, FIXME, HACK, XXX, BUG, NOTE)",
"Analyze git history for problematic patterns and recent hotfixes",
"Extract existing test coverage reports and metrics",
"Identify code analysis tools already in use (SonarQube, CodeClimate, etc.)"
]
}
]
},
{
"phase": 2,
"name": "Systematic Bug Discovery",
"bug_categories": [
{
"category": "CRITICAL",
"severity": "P0",
"types": [
"SQL Injection vulnerabilities",
"Cross-Site Scripting (XSS) flaws",
"Cross-Site Request Forgery (CSRF) vulnerabilities",
"Authentication/Authorization bypass",
"Remote Code Execution (RCE) risks",
"Data corruption or permanent data loss",
"System crashes, deadlocks, or infinite loops",
"Memory leaks and resource exhaustion",
"Insecure cryptographic implementations",
"Hardcoded secrets or credentials"
]
},
{
"category": "FUNCTIONAL",
"severity": "P1-P2",
"types": [
"Logic errors (incorrect conditionals, wrong calculations, off-by-one errors)",
"State management issues (race conditions, stale state, improper mutations)",
"Incorrect API contracts or request/response mappings",
"Missing or insufficient input validation",
"Broken business logic or workflow violations",
"Incorrect data transformations or serialization",
"Type mismatches or unsafe type coercions",
"Incorrect exception handling or error propagation"
]
},
{
"category": "INTEGRATION",
"severity": "P2",
"types": [
"Incorrect external API usage or outdated endpoints",
"Database query errors, SQL syntax issues, or N+1 problems",
"Message queue handling failures (RabbitMQ, Kafka, SQS)",
"File system operation errors (permissions, path traversal)",
"Network communication issues (timeouts, retries, connection pooling)",
"Cache inconsistency or invalidation problems",
"Third-party library misuse or version incompatibilities"
]
},
{
"category": "EDGE_CASES",
"severity": "P2-P3",
"types": [
"Null/undefined/nil/None pointer dereferences",
"Empty array/list/collection handling",
"Zero or negative value edge cases",
"Boundary conditions (max/min integers, string length limits)",
"Missing error handling or swallowed exceptions",
"Timeout and retry logic failures",
"Concurrent access issues without proper locking",
"Overflow/underflow in numeric operations"
]
},
{
"category": "CODE_QUALITY",
"severity": "P3-P4",
"types": [
"Deprecated API usage",
"Dead code or unreachable code paths",
"Circular dependencies",
"Performance bottlenecks (inefficient algorithms, redundant operations)",
"Missing or incorrect type annotations",
"Inconsistent error handling patterns",
"Resource leaks (file handles, database connections, network sockets)",
"Improper logging (sensitive data exposure, insufficient context)"
]
}
],
"discovery_methods": [
"Static code analysis using language-specific tools",
"Pattern matching for common anti-patterns and code smells",
"Dependency vulnerability scanning (npm audit, pip-audit, bundle-audit, cargo audit)",
"Control flow and data flow analysis",
"Dead code detection",
"Configuration validation against best practices",
"Documentation-to-implementation cross-verification",
"Security-focused code review"
]
},
{
"phase": 3,
"name": "Bug Documentation & Prioritization",
"bug_report_schema": {
"bug_id": "Sequential identifier (BUG-001, BUG-002, etc.)",
"severity": {
"type": "enum",
"values": [
"CRITICAL",
"HIGH",
"MEDIUM",
"LOW"
],
"description": "Bug severity level"
},
"category": {
"type": "enum",
"values": [
"SECURITY",
"FUNCTIONAL",
"PERFORMANCE",
"INTEGRATION",
"CODE_QUALITY"
],
"description": "Bug classification"
},
"location": {
"files": [
"Array of affected file paths with line numbers"
],
"component": "Module/Service/Feature name",
"function": "Specific function or method name"
},
"description": {
"current_behavior": "What's broken or wrong",
"expected_behavior": "What should happen instead",
"root_cause": "Technical explanation of why it's broken"
},
"impact_assessment": {
"user_impact": "Effect on end users (data loss, security exposure, UX degradation)",
"system_impact": "Effect on system (performance, stability, scalability)",
"business_impact": "Effect on business (compliance, revenue, reputation, legal)"
},
"reproduction": {
"steps": [
"Step-by-step instructions to reproduce"
],
"test_data": "Sample data or conditions needed",
"actual_result": "What happens when reproduced",
"expected_result": "What should happen"
},
"verification": {
"code_snippet": "Demonstrative code showing the bug",
"test_case": "Test that would fail due to this bug",
"logs_or_metrics": "Evidence from logs or monitoring"
},
"dependencies": {
"related_bugs": [
"Array of related BUG-IDs"
],
"blocking_issues": [
"Array of bugs that must be fixed first"
],
"blocked_by": [
"External factors preventing fix"
]
},
"metadata": {
"discovered_date": "ISO 8601 timestamp",
"discovered_by": "Tool or method used",
"cve_id": "If applicable, CVE identifier",
"cwe_id": "If applicable, CWE identifier"
}
},
"prioritization_matrix": {
"criteria": [
{
"factor": "severity",
"weight": 0.4,
"scale": "CRITICAL=100, HIGH=70, MEDIUM=40, LOW=10"
},
{
"factor": "user_impact",
"weight": 0.3,
"scale": "All users=100, Many=70, Some=40, Few=10"
},
{
"factor": "fix_complexity",
"weight": 0.15,
"scale": "Simple=100, Medium=60, Complex=20"
},
{
"factor": "regression_risk",
"weight": 0.15,
"scale": "Low=100, Medium=60, High=20"
}
],
"formula": "priority_score = Σ(factor_value × weight)"
}
},
{
"phase": 4,
"name": "Fix Implementation",
"fix_workflow": [
{
"step": 1,
"action": "Create isolated fix branch",
"naming": "fix/BUG-{id}-{short-description}"
},
{
"step": 2,
"action": "Write failing test FIRST",
"rationale": "Test-Driven Development ensures fix is verifiable"
},
{
"step": 3,
"action": "Implement minimal, focused fix",
"principle": "Smallest change that correctly resolves the issue"
},
{
"step": 4,
"action": "Verify test now passes",
"validation": "Run specific test and related test suite"
},
{
"step": 5,
"action": "Run full regression test suite",
"validation": "Ensure no existing functionality breaks"
},
{
"step": 6,
"action": "Update documentation",
"scope": "API docs, inline comments, changelog"
}
],
"fix_principles": [
"MINIMAL_CHANGE: Make the smallest change that correctly fixes the issue",
"NO_SCOPE_CREEP: Avoid unrelated refactoring or feature additions",
"BACKWARDS_COMPATIBLE: Preserve existing API contracts unless bug itself is breaking",
"FOLLOW_CONVENTIONS: Adhere to project's existing code style and patterns",
"DEFENSIVE_PROGRAMMING: Add guards to prevent similar bugs in the future",
"EXPLICIT_OVER_IMPLICIT: Make intent clear through code structure and comments",
"FAIL_FAST: Validate inputs early and fail with clear error messages"
],
"code_review_checklist": [
"Fix addresses root cause, not just symptoms",
"All edge cases are properly handled",
"Error messages are clear, actionable, and don't expose sensitive info",
"Performance impact is acceptable (no O(n²) where O(n) suffices)",
"Security implications thoroughly considered",
"No new compiler warnings or linting errors",
"Changes are covered by tests",
"Documentation is updated and accurate",
"Breaking changes are clearly marked and justified",
"Dependencies are up-to-date and secure"
]
},
{
"phase": 5,
"name": "Testing & Validation",
"test_requirements": {
"mandatory_tests_per_fix": [
{
"type": "unit_test",
"description": "Isolated test for the specific bug fix",
"coverage": "Must cover the exact code path that was broken"
},
{
"type": "integration_test",
"description": "Test if bug involves multiple components",
"coverage": "End-to-end flow through affected systems"
},
{
"type": "regression_test",
"description": "Ensure fix doesn't break existing functionality",
"coverage": "All related features and code paths"
},
{
"type": "edge_case_tests",
"description": "Cover boundary conditions and corner cases",
"coverage": "Null values, empty inputs, limits, error conditions"
}
]
},
"test_structure_template": {
"description": "Language-agnostic test structure",
"template": [
"describe('BUG-{ID}: {description}', () => {",
" test('reproduces original bug', () => {",
" // This test demonstrates the bug existed",
" // Should fail before fix, pass after",
" });",
"",
" test('verifies fix resolves issue', () => {",
" // This test proves correct behavior after fix",
" });",
"",
" test('handles edge case: {case}', () => {",
" // Additional coverage for related scenarios",
" });",
"});"
]
},
"validation_steps": [
{
"step": "Run full test suite",
"commands": {
"javascript": "npm test",
"python": "pytest",
"go": "go test ./...",
"java": "mvn test",
"ruby": "bundle exec rspec",
"rust": "cargo test",
"php": "phpunit"
}
},
{
"step": "Measure code coverage",
"tools": [
"Istanbul/NYC",
"Coverage.py",
"JaCoCo",
"SimpleCov",
"Tarpaulin"
]
},
{
"step": "Run static analysis",
"tools": [
"ESLint",
"Pylint",
"golangci-lint",
"SpotBugs",
"Clippy"
]
},
{
"step": "Performance benchmarking",
"condition": "If fix affects hot paths or critical operations"
},
{
"step": "Security scanning",
"tools": [
"Snyk",
"OWASP Dependency-Check",
"Trivy",
"Bandit"
]
}
]
},
{
"phase": 6,
"name": "Documentation & Reporting",
"fix_documentation_requirements": [
"Update inline code comments explaining the fix and why it was necessary",
"Revise API documentation if behavior changed",
"Update CHANGELOG.md with bug fix entry",
"Create or update troubleshooting guides",
"Document any workarounds for deferred/unfixed issues",
"Add migration notes if fix requires user action"
],
"executive_summary_template": {
"title": "Bug Fix Report - {repository_name}",
"metadata": {
"date": "ISO 8601 date",
"analyzer": "Tool/Person name",
"repository": "Full repository path",
"commit_hash": "Git commit SHA",
"duration": "Analysis duration in hours"
},
"overview": {
"total_bugs_found": "integer",
"total_bugs_fixed": "integer",
"bugs_deferred": "integer",
"test_coverage_before": "percentage",
"test_coverage_after": "percentage",
"files_analyzed": "integer",
"lines_of_code": "integer"
},
"critical_findings": [
"Top 3-5 most critical bugs found and their fixes"
],
"fix_summary_by_category": {
"security": "count",
"functional": "count",
"performance": "count",
"integration": "count",
"code_quality": "count"
},
"detailed_fix_table": {
"columns": [
"BUG-ID",
"File",
"Line",
"Category",
"Severity",
"Description",
"Status",
"Test Added"
],
"format": "Markdown table or CSV"
},
"risk_assessment": {
"remaining_high_priority": [
"List of unfixed critical issues"
],
"recommended_next_steps": [
"Prioritized action items"
],
"technical_debt": [
"Summary of identified tech debt"
],
"breaking_changes": [
"Any backwards-incompatible fixes"
]
},
"testing_results": {
"test_command": "Exact command used to run tests",
"tests_passed": "X out of Y",
"tests_failed": "count with reasons",
"tests_added": "count",
"coverage_delta": "+X% or -X%"
}
},
"deliverables_checklist": [
"All bugs documented in standardized format",
"Fixes implemented with minimal scope",
"Test suite updated and passing",
"Documentation updated (code, API, user guides)",
"Code review completed and approved",
"Performance impact assessed and acceptable",
"Security review conducted for security-related fixes",
"Deployment notes and rollback plan prepared",
"Changelog updated with user-facing changes",
"Stakeholders notified of critical fixes"
]
},
{
"phase": 7,
"name": "Continuous Improvement",
"pattern_analysis": {
"objectives": [
"Identify recurring bug patterns across codebase",
"Detect architectural issues enabling bugs",
"Find gaps in testing strategy",
"Highlight areas with technical debt"
],
"outputs": [
"Common bug pattern report",
"Preventive measure recommendations",
"Tooling improvement suggestions",
"Architectural refactoring proposals"
]
},
"monitoring_recommendations": {
"metrics_to_track": [
"Bug discovery rate over time",
"Time to resolution by severity",
"Regression rate (bugs reintroduced)",
"Test coverage percentage",
"Code churn in bug-prone areas",
"Dependency vulnerability count"
],
"alerting_rules": [
"Critical security vulnerabilities in dependencies",
"Test suite failures",
"Code coverage drops below threshold",
"Performance degradation in key operations"
],
"logging_improvements": [
"Add structured logging where missing",
"Include correlation IDs for request tracing",
"Log security-relevant events",
"Ensure error logs include stack traces and context"
]
}
}
],
"constraints_and_best_practices": [
"NEVER compromise security for simplicity or convenience",
"MAINTAIN complete audit trail of all changes",
"FOLLOW semantic versioning if fixes change public API",
"RESPECT rate limits when testing external services",
"USE feature flags for high-risk or gradual rollout fixes",
"DOCUMENT all assumptions made during analysis",
"CONSIDER rollback strategy for every fix",
"PREFER backwards-compatible fixes when possible",
"AVOID introducing new dependencies without justification",
"TEST in multiple environments when applicable"
],
"output_formats": [
{
"format": "markdown",
"purpose": "Human-readable documentation and reports",
"filename_pattern": "bug_report_{date}.md"
},
{
"format": "json",
"purpose": "Machine-readable for automated processing",
"filename_pattern": "bug_data_{date}.json",
"schema": "Follow bug_report_schema defined in Phase 3"
},
{
"format": "csv",
"purpose": "Import into bug tracking systems (Jira, GitHub Issues)",
"filename_pattern": "bugs_{date}.csv",
"columns": [
"BUG-ID",
"Severity",
"Category",
"File",
"Line",
"Description",
"Status"
]
},
{
"format": "yaml",
"purpose": "Configuration-friendly format for CI/CD integration",
"filename_pattern": "bug_config_{date}.yaml"
}
],
"special_considerations": {
"monorepos": "Analyze each package/workspace separately with cross-package dependency tracking",
"microservices": "Consider inter-service contracts, API compatibility, and distributed tracing",
"legacy_code": "Balance fix risk vs benefit; prioritize high-impact, low-risk fixes",
"third_party_dependencies": "Report vulnerabilities upstream; consider alternatives if unmaintained",
"high_traffic_systems": "Consider deployment strategies (blue-green, canary) for fixes",
"regulated_industries": "Ensure compliance requirements met (HIPAA, PCI-DSS, SOC2, GDPR)",
"open_source_projects": "Follow contribution guidelines; engage with maintainers before large changes"
},
"success_criteria": {
"quantitative": [
"All CRITICAL and HIGH severity bugs addressed",
"Test coverage increased by at least X%",
"Zero security vulnerabilities in dependencies",
"All tests passing",
"Code quality metrics improved (cyclomatic complexity, maintainability index)"
],
"qualitative": [
"Codebase is more maintainable",
"Documentation is clear and comprehensive",
"Team can confidently deploy fixes",
"Future bug prevention mechanisms in place",
"Development velocity improved"
]
}
}