What is the exact required JSON structure?

The output must be a single JSON object containing pass_summary and an issues array. Each issue must include severity, title, description, file, line, and suggested_fix.

How should line numbers be represented?

Use a number when the issue is tied to a specific line; otherwise use null.

What are the severity levels and when to apply them?

Using must_fix for security, runtime, or breaking changes; should_fix for performance or maintainability; suggestion for minor refinements.

lookagain-output-format

npx machina-cli add skill HartBrook/lookagain/lookagain-output-format --openclaw

Files (1)

SKILL.md

1.3 KB

Code Review Output Format

When performing code reviews, output findings in this exact JSON structure:

{
  "pass_summary": "string - Brief summary of review scope and key findings",
  "issues": [
    {
      "severity": "must_fix | should_fix | suggestion",
      "title": "string - Brief title (max 100 chars)",
      "description": "string - Detailed explanation of the issue",
      "file": "string - Relative file path",
      "line": "number | null - Line number if applicable",
      "suggested_fix": "string - How to fix it"
    }
  ]
}

Severity Definitions

must_fix:

Security vulnerabilities
Bugs causing runtime errors
Data loss/corruption risks
Breaking API changes

should_fix:

Performance issues
Poor error handling
Missing edge cases
Maintainability concerns

suggestion:

Minor refactoring
Documentation gaps
Style improvements

Rules

Output ONLY valid JSON (no markdown wrapper)
Include all fields for each issue
Use null for optional fields (like line) when not applicable
Keep titles concise and descriptive
Make suggested_fix actionable

Source

git clone https://github.com/HartBrook/lookagain/blob/main/src/skills/lookagain-output-format/SKILL.mdView on GitHub

Overview

Defines the exact JSON structure for code review findings to ensure consistent, parseable outputs. It standardizes pass_summary and an issues array with fields like severity, title, description, file, line, and suggested_fix.

How This Skill Works

Reviewers populate the schema exactly as defined, emitting a single root JSON object. The schema enforces the three severity tiers (must_fix, should_fix, suggestion), includes all issue fields, and uses null for optional fields like line to keep tooling predictable.

When to Use It

During code reviews to produce machine-readable, consistent findings.
When integrating reviews with CI/CD pipelines and issue trackers.
For reporting security, runtime, or API-breaking issues in changes.
When auditing code quality across a repository.
When generating developer-facing release notes from review outputs.

Quick Start

Step 1: Review the code and map findings to pass_summary and issues.
Step 2: Fill out each issue with severity, title, description, file, line, and suggested_fix using the exact keys.
Step 3: Output a valid JSON object and validate it before sharing.

Best Practices

Emit a single root JSON object per review run.
Populate all fields for every issue; use null for line when not applicable.
Choose the correct severity value and map issues to must_fix, should_fix, or suggestion.
Keep titles under 100 chars and descriptions precise and actionable.
Validate with a JSON linter and keep examples aligned with the schema.

Example Use Cases

Example 1: A must_fix issue in src/auth/login.ts with line 42 and a suggested_fix to add rate limiting.
Example 2: A should_fix performance issue in data-loader.ts due to missing memoization.
Example 3: A suggestion to improve documentation for an API endpoint in api/v1/docs.md.
Example 4: A must_fix runtime error caused by a null dereference in utils/parser.ts at line 128.
Example 5: Multiple issues with mixed severities in services/user.ts, illustrating a complete pass_summary.

Frequently Asked Questions

Add this skill to your agents