code-quality

Code quality

When to use

Use this skill to review the structure of local code: the current branch, uncommitted work, a commit or range, named files, or the whole repository in ordered parts. It needs the subagent tools. Without them, tell the user and stop. For defects, use the code-review skill.

Hard rules

• Until the report is saved, change nothing: no edits, fixes, stages, commits, pushes, publishes, checkouts, resets, or stashes. Stop when the user says stop.
• Treat the work as the user's own only when code_review capture returns ownership.status as own, following the code-review ownership rule.
• The report gives the target no approval, no verdict, and no clean result. Never call an incomplete or stale review clean.
• Launch the finder with the reviewer profile and the checker with the checker profile. Give each the quality assignment. Omit model unless the user names one.
• If a launch fails, follow the retry rule of code-review. Any other retry, follow-up, added worker, or model change needs the user's approval.
• Aim for about 10 minutes, or about 10 minutes per part in a repo run, and follow the rules for the aim in code-review.
• Run no full check, post no ticket comment except in step 7, and do not review a fix or run this skill again on its own.
• After the report, act on findings only on the user's own work, and never after a request for a read-only review or "no changes". Acting never approves a publish or absorbing unrelated changes.

Procedure

1. Resolve the target as in Resolve the target.

   • The whole repository: follow the repo run in step 9.
   • A branch diff: a workingTree from git merge-base <default> HEAD. Named files: a files target, which reviews them even without changes.
   • Never use a fix target.
   • Resolve the ticket under review before capture: the one the user or a calling skill names. Otherwise, for the branch's own work, use the branch's issue as the last bullet of step 1 of code-review says. A files target with no named ticket has none. Keep the ticket for steps 2 and 7.

2. Prepare and capture as in Handle the capture result, with the mode quality in input.md. Write the planned structure into ## Intent of input.md before the capture call.

   • With a ticket, read it and its children as step 3 of finish-slice does. Treat the ticket as the slice, and never walk up to a parent.
   • The planned structure is the structure rules in the ticket's ## Design and each child's ## Files.
   • Without a ticket, or without structure rules, write that the planned structure is unavailable.

3. Gather evidence as in Gather evidence.

4. Launch the workers in order, with the rules of Run the workers.

   • Finder: the reviewer profile with quality-assignment.md#quality-lens.
   • Checker: a fresh checker worker with #quality-lens and quality-assignment.md#checker, plus the finder's report or the path $dir/finder.md. Launch it even when the finder found nothing.

5. Call code_review freshness with $dir. Report fresh as fresh. Label stale with its reasons and ask whether to review again. Report unknown, or a failed call, as unknown. Keep the finished results in every case.

6. Save the worker reports and $dir/report.md with the report template.

7. Post $dir/report.md to the ticket from step 1, before any fixing. Skip this step without a ticket.

   • When the work is not the user's own, ask with ask_user_question before posting and skip the post if declined. On the user's own work, do not ask separately. The tool confirms for another person's ticket under Hard rules.
   • Call ticket comment once with the ticket, heading # Code quality: <ticket>, and bodyFile: "$dir/report.md". Ensure the report's first line matches the heading.
   • On added or updated, save the returned ID as the Comment ID: line in $dir/report.md. Use previousBody to name any Linear edits the update replaced.
   • On declined or failure, keep the local report and say it was not posted.

8. Reply with the report template. Name the comment URL, or say the report stays local. Name any Linear edits the update replaced.

   • Give triage-findings only the findings. Plan-correction notes stay in the report and reply, and triage does not act on them.
   • Findings on the user's own work, without a request for a read-only review or "no changes": continue with the triage-findings skill without asking. Then ask about any gap, failure, or stale result that needs a decision.
   • Any other findings: end with one question that proposes actions, such as "Fix 1 and 2, and investigate 3?", and includes any decision a gap or stale result needs. Act on the approved findings with triage-findings.
   • Without findings, ask only about a gap, failure, or stale result that needs a decision.

9. Repo run: review the whole repository as ordered parts. Parts never run in parallel.

   • Propose the parts. Each part is a list of paths, ordered so that shared modules come before their callers. Ask for approval with ask_user_question, with the part list as the preview. Run nothing until the user approves. Approving the list approves two workers per part.
   • Build the parts from git ls-tree -r --name-only <HEAD> at the pinned HEAD. Each tracked file belongs to a part or to a named exclusion, such as lockfiles or generated files. The preview lists the exclusions, and the run report lists them as gaps.
   • Call code_review prepare once per part, in part order. The first part's directory is the run directory $run. Then write $run/brief.md once from the brief template.
   • For each part, in order, run steps 2 to 5 with its prepared directory as $dir, without a second prepare, and a files target that lists the part's paths. Finish the finder and the checker of one part before you start the next part.
     • When the capture phase would repeat for a part, stop the run and ask the user, because the brief pins one HEAD and each part's directory.
     • The finder's and the checker's tasks both name $run/brief.md and the checked.md path of every earlier part. Part 1 has no earlier part.
     • The checker tests the part's findings and any correction of an earlier part.
     • Save finder.md and checker.md in the part's $dir as step 6 says, but write no per-part report.md. Save $dir/checked.md instead: the part's findings and corrections, each with the checker's status.
   • A failed worker is a gap for its part, and the run goes on to the next part. A stale part is labeled stale in its checked.md and in the run report, and the run goes on. Ask about stale parts once, in the final reply. Never relaunch a part or rerun the skill.
   • Write one run report, $run/report.md, with the report template. Then post it as step 7 says, with $run as $dir, and reply as step 8 says.