catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Simplify and streamline agent documentation and output schemas for clarity and consistency

Browse Source
This commit is contained in:
catlog22
2025-11-26 09:37:14 +08:00
parent e70f086b7e
commit 84c180ab66
5 changed files with 139 additions and 756 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
.claude/commands/workflow/review-fix.md
View File

@@ -224,55 +224,7 @@ if (result.passRate < 100%) {
- TodoWrite completion: Mark all phases done
- Output summary to user with dashboard link
### Planning Agent (@cli-planning-agent)
**Role**: Analyze findings, create execution strategy, initialize progress tracking
**Orchestrator Provides**:
- Review findings data (id, title, severity, file, description, recommendations)
- Project context (structure, test framework, git status)
- Output directory and template paths
**Agent Outputs**:
- fix-plan.json (groups, timeline, execution strategy)
- fix-progress-{N}.json (one per group, initial state)
### Execution Agent (@cli-execute-agent)
**Role**: Execute fixes for assigned group, update progress in real-time
**Orchestrator Provides**:
- Group assignment (from fix-plan.json)
- Fix strategy and risk assessment (from fix-plan.json)
- Progress file path (fix-progress-{N}.json)
**Agent Responsibilities**:
- Read/update assigned progress file
- Apply fixes with flow control tracking
- Run tests and verify
- Commit successful fixes to git
## Reference
### CLI Tool Configuration
**Planning Agent**:
```javascript
{
subagent_type: "cli-planning-agent",
timeout: 300000, // 5 minutes for planning
description: "Generate fix plan for N code review findings"
}
```
**Execution Agent**:
```javascript
{
subagent_type: "cli-execute-agent",
timeout: 3600000, // 60 minutes per group (adjustable)
description: "Fix M issues: {group_name}"
}
```
### Output File Structure

81
.claude/commands/workflow/review-module-cycle.md
View File

@@ -263,73 +263,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
- TodoWrite completion: Mark all tasks done
- Output: Dashboard path and REVIEW-SUMMARY.md path to user
### Review Agent (@cli-explore-agent)
**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis)
**Context Provided by Orchestrator**:
```javascript
{
dimension: "security|architecture|quality|...",
review_type: "module",
target_files: ["src/auth/service.ts", "src/auth/validator.ts", ...],
output_paths: {
json: "{output-dir}/dimensions/{dimension}.json",
report: "{output-dir}/reports/{dimension}-analysis.md",
cli_output: "{output-dir}/reports/{dimension}-cli-output.txt"
},
cli_config: {
tool: "gemini",
template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt",
timeout: 3600000,
mode: "analysis"
}
}
```
**Deliverables**:
1. Dimension JSON with findings array (see JSON Schema below)
2. Analysis markdown report with summary and recommendations
3. CLI output log for debugging
### Deep-Dive Agent (@cli-explore-agent)
**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context)
**Context Provided**:
```javascript
{
finding_id: "uuid",
original_finding: {...},
iteration: 1,
output_paths: {
json: "{output-dir}/iterations/iteration-1-finding-{uuid}.json",
report: "{output-dir}/reports/deep-dive-1-{uuid}.md"
},
cli_config: {
tool: "gemini",
template: "01-diagnose-bug-root-cause.txt",
timeout: 2400000
}
}
```
**Deliverables**:
1. Deep-dive JSON with root cause, remediation plan, impact assessment
2. Analysis report with detailed recommendations
## Reference
### CLI Tool Configuration
**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute)
**Tool Details**:
1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout
2. **Qwen** (fallback): `coder-model` - 60min timeout
3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout
**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4
### Output File Structure
@@ -494,15 +428,17 @@ Task(
## CLI Configuration
- Tool Priority: gemini → qwen → codex (fallback chain)
- Template: ~/.claude/workflows/cli-templates/prompts/analysis/${dimensionTemplate}
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
- Timeout: ${timeout}ms
- Mode: analysis (READ-ONLY)
- Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}
## Expected Deliverables
**MANDATORY**: Before generating any JSON output, read the template example first:
- Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- Follow the exact structure and field naming from the example
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- MUST include: findings array with severity, file, line, description, recommendation
- MUST include: summary statistics (total findings, severity distribution)
- MUST include: cross_references to related findings
@@ -568,12 +504,15 @@ Task(
## CLI Configuration
- Tool Priority: gemini → qwen → codex
- Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
- Timeout: 2400000ms (40 minutes)
- Mode: analysis (READ-ONLY)
## Expected Deliverables
**MANDATORY**: Before generating any JSON output, read the template example first:
- Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- Follow the exact structure and field naming from the example
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- MUST include: root_cause with summary, details, affected_scope, similar_patterns
- MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level
- MUST include: impact_assessment with files_affected, tests_required, breaking_changes

89
.claude/commands/workflow/review-session-cycle.md
View File

@@ -249,84 +249,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
- TodoWrite completion: Mark all tasks done
- Output: Dashboard path and REVIEW-SUMMARY.md path to user
### Review Agent (@cli-explore-agent)
**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis)
**Context Provided by Orchestrator**:
```javascript
{
dimension: "security|architecture|quality|...",
session_id: "WFS-xxx",
session_metadata_path: ".workflow/active/WFS-xxx/workflow-session.json",
summaries_dir: ".workflow/active/WFS-xxx/.summaries/",
output_paths: {
json: ".review-cycle/dimensions/{dimension}.json",
report: ".review-cycle/reports/{dimension}-analysis.md",
cli_output: ".review-cycle/reports/{dimension}-cli-output.txt"
},
cli_config: {
tool: "gemini",
template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt",
timeout: 3600000,
mode: "analysis"
}
}
```
**Deliverables**:
1. Dimension JSON with findings array (see JSON Schema below)
2. Analysis markdown report with summary and recommendations
3. CLI output log for debugging
### Deep-Dive Agent (@cli-explore-agent)
**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context)
**Context Provided**:
```javascript
{
finding_id: "uuid",
original_finding: {...},
iteration: 1,
output_paths: {
json: ".review-cycle/iterations/iteration-1-finding-{uuid}.json",
report: ".review-cycle/reports/deep-dive-1-{uuid}.md"
},
cli_config: {
tool: "gemini",
template: "01-diagnose-bug-root-cause.txt",
timeout: 2400000
}
}
```
**Deliverables**:
1. Deep-dive JSON with root cause, remediation plan, impact assessment
2. Analysis report with detailed recommendations
### Features Summary
- **Real-time Progress**: Phase indicator, progress bar, agent status (auto-refresh 5s)
- **Interactive Findings**: Severity/dimension filtering, search, sort, detail drawer
- **Export**: Generate markdown report
- **Dark Mode**: Toggle with localStorage persistence
**Usage Details**: See `~/.claude/workflows/DASHBOARD-QUICKSTART.md`
## Reference
### CLI Tool Configuration
**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute)
**Tool Details**:
1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout
2. **Qwen** (fallback): `coder-model` - 60min timeout
3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout
**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4
### Session File Structure
@@ -520,8 +443,12 @@ Task(
- Mode: analysis (READ-ONLY)
## Expected Deliverables
**MANDATORY**: Before generating any JSON output, read the template example first:
- Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- Follow the exact structure and field naming from the example
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
- MUST include: findings array with severity, file, line, description, recommendation
- MUST include: summary statistics (total findings, severity distribution)
- MUST include: cross_references to related findings
@@ -591,8 +518,12 @@ Task(
- Mode: analysis (READ-ONLY)
## Expected Deliverables
**MANDATORY**: Before generating any JSON output, read the template example first:
- Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- Follow the exact structure and field naming from the example
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
- MUST include: root_cause with summary, details, affected_scope, similar_patterns
- MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level
- MUST include: impact_assessment with files_affected, tests_required, breaking_changes

355
.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
View File

@@ -1,291 +1,82 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Review Deep-Dive Results Schema",
"description": "Output schema for cli-explore-agent deep-dive iteration analysis. Contains root cause analysis, remediation plan, and impact assessment for critical findings.",
"type": "object",
"required": [
"finding_id",
"original_dimension",
"iteration",
"analysis_timestamp",
"cli_tool_used",
"root_cause",
"remediation_plan",
"impact_assessment",
"reassessed_severity",
"confidence_score",
"status"
],
"properties": {
"finding_id": {
"type": "string",
"description": "Original finding ID from dimension analysis",
"example": "sec-001-a1b2c3d4"
},
"original_dimension": {
"type": "string",
"enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
"description": "Dimension where finding was originally discovered"
},
"iteration": {
"type": "integer",
"minimum": 1,
"description": "Deep-dive iteration number"
},
"analysis_timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO8601 timestamp when deep-dive completed"
},
"cli_tool_used": {
"type": "string",
"enum": ["gemini", "qwen", "codex"],
"description": "CLI tool used for deep-dive analysis"
},
[
{
"finding_id": "sec-001-a1b2c3d4",
"original_dimension": "security",
"iteration": 1,
"analysis_timestamp": "2025-01-25T14:40:15Z",
"cli_tool_used": "gemini",
"root_cause": {
"type": "object",
"required": ["summary", "details", "affected_scope"],
"properties": {
"summary": {
"type": "string",
"description": "One-sentence root cause summary"
},
"details": {
"type": "string",
"description": "Detailed explanation with history and context"
},
"affected_scope": {
"type": "string",
"description": "Full scope of affected code"
},
"similar_patterns": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of file:function where similar issue exists"
}
}
"summary": "Legacy code from v1 migration, pre-ORM implementation",
"details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.",
"affected_scope": "All query-builder.ts methods using string template literals (15 methods total)",
"similar_patterns": [
"src/database/user-queries.ts:buildEmailQuery",
"src/database/order-queries.ts:buildOrderSearch"
]
},
"remediation_plan": {
"type": "object",
"required": ["approach", "priority", "estimated_effort", "risk_level", "steps"],
"properties": {
"approach": {
"type": "string",
"description": "High-level fix strategy"
"approach": "Migrate to ORM prepared statements with input validation layer",
"priority": "P0 - Critical (security vulnerability)",
"estimated_effort": "4 hours development + 2 hours testing",
"risk_level": "low",
"steps": [
{
"step": 1,
"action": "Replace direct string concatenation with ORM query builder",
"files": ["src/database/query-builder.ts:buildUserQuery:140-150"],
"commands": [
"Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;",
"With: return db('users').where('id', userId).first();"
],
"rationale": "ORM automatically parameterizes queries, eliminating injection risk",
"validation": "Run: npm test -- src/database/query-builder.test.ts"
},
"priority": {
"type": "string",
"pattern": "^P[0-2] - ",
"description": "Priority level with severity label",
"examples": ["P0 - Critical (security vulnerability)", "P1 - High (performance bottleneck)"]
{
"step": 2,
"action": "Add input validation layer before ORM",
"files": ["src/database/validators.ts:validateUserId:NEW"],
"commands": [
"Create validator: export function validateUserId(id: unknown): number { ... }",
"Add schema: z.number().positive().int()"
],
"rationale": "Defense in depth - validate types and ranges before database layer",
"validation": "Run: npm test -- src/database/validators.test.ts"
},
"estimated_effort": {
"type": "string",
"description": "Estimated time for development and testing",
"example": "4 hours development + 2 hours testing"
},
"risk_level": {
"type": "string",
"enum": ["low", "medium", "high"],
"description": "Risk level of implementing the fix"
},
"steps": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": ["step", "action", "files", "commands", "rationale", "validation"],
"properties": {
"step": {
"type": "integer",
"minimum": 1,
"description": "Step sequence number"
},
"action": {
"type": "string",
"description": "What to do in this step"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "Files to modify with function:lines format",
"examples": ["src/database/query-builder.ts:buildUserQuery:140-150"]
},
"commands": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific code changes or commands to execute"
},
"rationale": {
"type": "string",
"description": "Why this step is needed"
},
"validation": {
"type": "string",
"description": "How to verify step completion (test command)",
"example": "Run: npm test -- src/database/query-builder.test.ts"
}
}
}
},
"rollback_strategy": {
"type": "string",
"description": "How to safely revert changes if needed"
{
"step": 3,
"action": "Apply pattern to all 15 similar methods",
"files": ["src/database/query-builder.ts:ALL_METHODS"],
"commands": ["Bulk replace string templates with ORM syntax"],
"rationale": "Prevent similar vulnerabilities in other query methods",
"validation": "Run: npm test -- src/database/"
}
}
],
"rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring."
},
"impact_assessment": {
"type": "object",
"required": ["files_affected", "tests_required", "breaking_changes"],
"properties": {
"files_affected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Files affected with action type",
"examples": ["src/database/query-builder.ts (modify)", "src/database/validators.ts (new)"]
},
"tests_required": {
"type": "array",
"items": {
"type": "string"
},
"description": "Test files required with action type",
"examples": ["src/database/query-builder.test.ts (update existing)", "src/database/validators.test.ts (new)"]
},
"breaking_changes": {
"type": "boolean",
"description": "Whether this fix introduces breaking changes"
},
"dependencies_updated": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dependencies that need updating",
"examples": ["knex@2.5.1 (ORM library)"]
},
"deployment_notes": {
"type": "string",
"description": "Special deployment considerations"
}
}
},
"reassessed_severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low"],
"description": "Updated severity after deep analysis"
},
"severity_change_reason": {
"type": "string",
"description": "Justification for severity change (or 'No change')"
},
"confidence_score": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Confidence level of analysis (0.0-1.0)"
},
"references": {
"type": "array",
"items": {
"type": "string"
},
"description": "Project-specific and external documentation references"
},
"status": {
"type": "string",
"enum": ["remediation_plan_ready", "resolved"],
"description": "Status after deep-dive analysis"
}
},
"examples": [
{
"finding_id": "sec-001-a1b2c3d4",
"original_dimension": "security",
"iteration": 1,
"analysis_timestamp": "2025-01-25T14:40:15Z",
"cli_tool_used": "gemini",
"root_cause": {
"summary": "Legacy code from v1 migration, pre-ORM implementation",
"details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.",
"affected_scope": "All query-builder.ts methods using string template literals (15 methods total)",
"similar_patterns": [
"src/database/user-queries.ts:buildEmailQuery",
"src/database/order-queries.ts:buildOrderSearch"
]
},
"remediation_plan": {
"approach": "Migrate to ORM prepared statements with input validation layer",
"priority": "P0 - Critical (security vulnerability)",
"estimated_effort": "4 hours development + 2 hours testing",
"risk_level": "low",
"steps": [
{
"step": 1,
"action": "Replace direct string concatenation with ORM query builder",
"files": ["src/database/query-builder.ts:buildUserQuery:140-150"],
"commands": [
"Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;",
"With: return db('users').where('id', userId).first();"
],
"rationale": "ORM automatically parameterizes queries, eliminating injection risk",
"validation": "Run: npm test -- src/database/query-builder.test.ts"
},
{
"step": 2,
"action": "Add input validation layer before ORM",
"files": ["src/database/validators.ts:validateUserId:NEW"],
"commands": [
"Create validator: export function validateUserId(id: unknown): number { ... }",
"Add schema: z.number().positive().int()"
],
"rationale": "Defense in depth - validate types and ranges before database layer",
"validation": "Run: npm test -- src/database/validators.test.ts"
},
{
"step": 3,
"action": "Apply pattern to all 15 similar methods",
"files": ["src/database/query-builder.ts:ALL_METHODS"],
"commands": ["Bulk replace string templates with ORM syntax"],
"rationale": "Prevent similar vulnerabilities in other query methods",
"validation": "Run: npm test -- src/database/"
}
],
"rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring."
},
"impact_assessment": {
"files_affected": [
"src/database/query-builder.ts (modify)",
"src/database/validators.ts (new)",
"src/database/user-queries.ts (modify)",
"src/database/order-queries.ts (modify)"
],
"tests_required": [
"src/database/query-builder.test.ts (update existing)",
"src/database/validators.test.ts (new)",
"integration/security/sql-injection.test.ts (new)"
],
"breaking_changes": false,
"dependencies_updated": ["knex@2.5.1 (ORM library)"],
"deployment_notes": "No downtime required. Database migrations not needed."
},
"reassessed_severity": "high",
"severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.",
"confidence_score": 0.95,
"references": [
"Project ORM migration guide: docs/architecture/orm-guide.md",
"Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where",
"Similar incident: TICKET-1234 (previous SQL injection fix)"
"files_affected": [
"src/database/query-builder.ts (modify)",
"src/database/validators.ts (new)",
"src/database/user-queries.ts (modify)",
"src/database/order-queries.ts (modify)"
],
"status": "remediation_plan_ready"
}
]
}
"tests_required": [
"src/database/query-builder.test.ts (update existing)",
"src/database/validators.test.ts (new)",
"integration/security/sql-injection.test.ts (new)"
],
"breaking_changes": false,
"dependencies_updated": ["knex@2.5.1 (ORM library)"],
"deployment_notes": "No downtime required. Database migrations not needed."
},
"reassessed_severity": "high",
"severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.",
"confidence_score": 0.95,
"references": [
"Project ORM migration guide: docs/architecture/orm-guide.md",
"Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where",
"Similar incident: TICKET-1234 (previous SQL injection fix)"
],
"status": "remediation_plan_ready"
}
]

322
.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
View File

@@ -1,281 +1,51 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Review Dimension Results Schema",
"description": "Output schema for cli-explore-agent dimension analysis results. Contains structured findings from security, architecture, quality, action-items, performance, maintainability, and best-practices reviews.",
"type": "object",
"required": ["dimension", "review_id", "analysis_timestamp", "cli_tool_used", "summary", "findings"],
"properties": {
"dimension": {
"type": "string",
"enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
"description": "Review dimension being analyzed"
},
"review_id": {
"type": "string",
"pattern": "^review-\\d{8}-\\d{6}$",
"description": "Unique review cycle identifier",
"example": "review-20250125-143022"
},
"analysis_timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO8601 timestamp when analysis completed"
},
"cli_tool_used": {
"type": "string",
"enum": ["gemini", "qwen", "codex"],
"description": "CLI tool used for analysis (fallback chain: gemini → qwen → codex)"
},
"model": {
"type": "string",
"description": "Model name/version used by CLI tool",
"examples": ["gemini-2.5-pro", "coder-model", "gpt-5.1-codex"]
},
"analysis_duration_ms": {
"type": "integer",
"minimum": 0,
"description": "Analysis duration in milliseconds"
},
[
{
"dimension": "security",
"review_id": "review-20250125-143022",
"analysis_timestamp": "2025-01-25T14:30:22Z",
"cli_tool_used": "gemini",
"model": "gemini-2.5-pro",
"analysis_duration_ms": 2145000,
"summary": {
"type": "object",
"required": ["total_findings", "critical", "high", "medium", "low", "files_analyzed", "lines_reviewed"],
"properties": {
"total_findings": {
"type": "integer",
"minimum": 0,
"description": "Total number of findings across all severities"
},
"critical": {
"type": "integer",
"minimum": 0,
"description": "Count of critical severity findings"
},
"high": {
"type": "integer",
"minimum": 0,
"description": "Count of high severity findings"
},
"medium": {
"type": "integer",
"minimum": 0,
"description": "Count of medium severity findings"
},
"low": {
"type": "integer",
"minimum": 0,
"description": "Count of low severity findings"
},
"files_analyzed": {
"type": "integer",
"minimum": 0,
"description": "Total number of files analyzed"
},
"lines_reviewed": {
"type": "integer",
"minimum": 0,
"description": "Total lines of code reviewed"
}
}
"total_findings": 15,
"critical": 2,
"high": 4,
"medium": 6,
"low": 3,
"files_analyzed": 47,
"lines_reviewed": 8932
},
"findings": {
"type": "array",
"description": "Array of findings discovered during analysis",
"items": {
"$ref": "#/definitions/unifiedFinding"
}
},
"cross_references": {
"type": "array",
"description": "Cross-references to findings in other dimensions",
"items": {
"type": "object",
"required": ["finding_id", "related_dimensions", "reason"],
"properties": {
"finding_id": {
"type": "string",
"description": "Finding ID that appears in multiple dimensions"
},
"related_dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of dimensions where this finding appears"
},
"reason": {
"type": "string",
"description": "Explanation of cross-reference relationship"
}
}
}
}
},
"definitions": {
"unifiedFinding": {
"type": "object",
"title": "Unified Finding Schema",
"description": "Standardized finding structure applicable to all review dimensions",
"required": ["id", "title", "severity", "category", "description", "file", "line", "snippet", "recommendation", "impact", "iteration", "status"],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique finding identifier (UUID v4)",
"example": "sec-001-a1b2c3d4"
},
"title": {
"type": "string",
"minLength": 10,
"maxLength": 100,
"description": "Short descriptive title (50-100 chars)"
},
"severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low"],
"description": "Severity level based on impact and risk"
},
"category": {
"type": "string",
"description": "Dimension-specific category (see CATEGORIES in review-cycle.md)",
"examples": ["injection", "coupling", "code-smell", "n-plus-one"]
},
"description": {
"type": "string",
"minLength": 50,
"description": "Detailed description with context (200-500 words)"
},
"file": {
"type": "string",
"description": "Relative path to affected file",
"example": "src/database/query-builder.ts"
},
"line": {
"type": "integer",
"minimum": 1,
"description": "Line number where issue occurs"
},
"snippet": {
"type": "string",
"description": "Code context (5-10 lines around the issue)"
},
"recommendation": {
"type": "string",
"description": "Actionable fix recommendation with code examples"
},
"impact": {
"type": "string",
"description": "Potential impact description (business + technical)"
},
"references": {
"type": "array",
"items": {
"type": "string"
},
"description": "Documentation URLs and standard references",
"examples": [
"OWASP Top 10 - A03:2021 Injection",
"https://owasp.org/www-community/attacks/SQL_Injection"
]
},
"findings": [
{
"id": "sec-001-a1b2c3d4",
"title": "SQL Injection vulnerability in user query",
"severity": "critical",
"category": "injection",
"description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.",
"file": "src/database/query-builder.ts",
"line": 145,
"snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
"recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])",
"references": [
"OWASP Top 10 - A03:2021 Injection",
"https://owasp.org/www-community/attacks/SQL_Injection"
],
"impact": "Potential data breach, unauthorized access to user records, data manipulation",
"metadata": {
"type": "object",
"description": "Dimension-specific metadata",
"properties": {
"cwe_id": {
"type": "string",
"description": "CWE identifier (for security findings)",
"example": "CWE-89"
},
"owasp_category": {
"type": "string",
"description": "OWASP category (for security findings)",
"example": "A03:2021-Injection"
},
"pattern_type": {
"type": "string",
"description": "Pattern type (for quality findings)",
"examples": ["anti-pattern", "code-smell"]
},
"complexity_score": {
"type": "number",
"description": "Cyclomatic complexity score (for quality findings)"
}
}
"cwe_id": "CWE-89",
"owasp_category": "A03:2021-Injection"
},
"iteration": {
"type": "integer",
"minimum": 0,
"description": "Iteration number when finding was discovered (0 = initial parallel phase)"
},
"status": {
"type": "string",
"enum": ["pending_remediation", "remediation_plan_ready", "resolved"],
"description": "Current status of finding"
},
"cross_references": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of dimensions where this finding also appears"
},
"reassessed_severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low"],
"description": "Updated severity if changed in deep-dive iteration"
}
"iteration": 0,
"status": "pending_remediation",
"cross_references": []
}
}
},
"examples": [
{
"dimension": "security",
"review_id": "review-20250125-143022",
"analysis_timestamp": "2025-01-25T14:30:22Z",
"cli_tool_used": "gemini",
"model": "gemini-2.5-pro",
"analysis_duration_ms": 2145000,
"summary": {
"total_findings": 15,
"critical": 2,
"high": 4,
"medium": 6,
"low": 3,
"files_analyzed": 47,
"lines_reviewed": 8932
},
"findings": [
{
"id": "sec-001-a1b2c3d4",
"title": "SQL Injection vulnerability in user query",
"severity": "critical",
"category": "injection",
"description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.",
"file": "src/database/query-builder.ts",
"line": 145,
"snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
"recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])",
"references": [
"OWASP Top 10 - A03:2021 Injection",
"https://owasp.org/www-community/attacks/SQL_Injection"
],
"impact": "Potential data breach, unauthorized access to user records, data manipulation",
"metadata": {
"cwe_id": "CWE-89",
"owasp_category": "A03:2021-Injection"
},
"iteration": 0,
"status": "pending_remediation",
"cross_references": []
}
],
"cross_references": [
{
"finding_id": "sec-001-a1b2c3d4",
"related_dimensions": ["quality", "architecture"],
"reason": "Same file flagged in multiple dimensions"
}
]
}
]
}
],
"cross_references": [
{
"finding_id": "sec-001-a1b2c3d4",
"related_dimensions": ["quality", "architecture"],
"reason": "Same file flagged in multiple dimensions"
}
]
}
]