Skip to content

Review

Logical ID: kiyo.review · Entry: src/kiyo/skills/review/SKILL.md · Procedure: workflows/review.md (KIYO-REVIEW-001)

Purpose

Section titled “Purpose”

Review inspects existing changes made by humans or AI and reports defects, risks, and suggestions. It never edits anything. Review alone does not authorize fixes or build and test execution.

Inputs:

  • staged or unstaged changes;
  • specified files;
  • an explicit commit range;
  • PR context available through actual authorized tools.

Without a supplied range, Review inspects the current workspace. It explains what was covered across staged, unstaged, and relevant untracked changes, and it never guesses a default branch. No diff means “no changes”, not invented findings.

Access contract

Section titled “Access contract”
  • Allowed: analysis and chat output.
  • Not allowed:
    • editing source, tests, config, or Memory;
    • creating report files by default;
    • installing packages;
    • committing, pushing, stashing, resetting, or cleaning the workspace.
  • No automatic execution: Review does not run builds, tests, formatters, scanners, project scripts, or application code. These can write artifacts, use the network, or change data. If execution is needed, Review proposes the check; running it is a separate, explicitly requested Test run.

Procedure

Section titled “Procedure”
  1. Resolve the comparison. Establish the accessible files and revisions, and keep index, working-tree, and supplied-revision evidence separate. Excluded or unavailable scope is stated. A missing base is never fetched or guessed.
  2. Read relevant Memory in check mode. Verify material claims against current code. Stale Memory is not truth, and it is not permission to sync.
  3. Inspect behavior and impact. Read enough callers, guards, contracts, and tests, across ten dimensions.
  4. Validate each candidate finding against existing protections and sourced requirements.
  5. Report prioritized findings with the finding template and the review report.
  6. Close under the Review row of the Definition of Done.

Ten review dimensions

Section titled “Ten review dimensions”
Dimension Focus
Requirement compliance Behavior versus the actual request, acceptance criteria, and accepted rules; missing rules stay Unknown
Behavior correctness Inputs, state transitions, edge cases, failure paths, actual callers
Architecture boundaries Real dependencies, ownership, contracts, approved intent
Maintainability Local clarity, cohesion, duplication, necessary scope
Validation / errors Trust boundaries, null or invalid input, actual error contracts
Compatibility Affected consumers, signatures, formats, versions, migrations
Test coverage Relevant test source and supplied results; file existence is not execution
Security Identity, object and tenant policy, effective guards; no live exploit
Dependency impact Declared and resolved changes, necessity, compatibility; no scanner runs
Governance evidence Established authorization and evidence of required checks

Classifying findings

Section titled “Classifying findings”

From framework/review-severity-confidence.md:

Category Evidence needed
Confirmed defect Inspected behavior and a supported trigger conflict with a sourced requirement or invariant, with protections examined. Static confirmation is not runtime reproduction
Plausible risk A concrete suspicious path with a material unresolved condition; the missing evidence is stated
Improvement suggestion A maintainability or design proposal without an established defect
  • Severity: CRITICAL, HIGH, MEDIUM, LOW, or INFO. It rates the finding’s impact if its condition holds.
  • Confidence: HIGH, MEDIUM, or LOW, always with a short basis. There are no invented percentages, and confidence is never raised because code was AI-generated.

Each finding cites an actual file and line or inspected range, the impact, the requirement or control, a suggested fix, and a verification idea. A suggested fix is not an applied fix.

Completion

Section titled “Completion”

DONE means the agreed bounded review was delivered. It does not mean defects are fixed, tests pass, or the application is production-ready. Tests not run remain NOT_RUN (never NOT_APPLICABLE). A missing required base or file prevents full completion.

Source and tests

Section titled “Source and tests”
  • Developer scenarios: tests/behavioral/review/scenarios.md (NOT_RUN)
  • Walkthrough WT-05: review manually edited code with an obvious null-handling bug, which is reported but not fixed
Section titled “Related”