Core Logic Review Prioritizer

Core Logic Design Review Support

The primary purpose of this skill is to help a human reviewer assess the design validity of business logic, core decision logic, and system-critical control logic in a short amount of time by organizing what to inspect, which design concerns matter, which questions to answer, and what next actions to take.

This is not a general-purpose code review replacement. Its job is to reshape a large change so human attention goes to the places where design judgment matters.

Responsibilities

This skill is responsible for:

• selecting the review targets a human should inspect deeply
• extracting design concerns from business logic and core decision logic changes
• surfacing the questions a human should explicitly check
• offering review-supporting views and review hypotheses
• suggesting next actions for the reviewer
• using visualization only when it meaningfully improves review

Non-Responsibilities

This skill is not responsible for:

• making the final judgment on design validity
• approving a change on behalf of a human
• performing a full general-purpose code quality review

Core Stance

• prioritize narrowing attention over reading everything
• prioritize business meaning and structural validity over surface neatness
• look at changes in responsibilities, boundaries, rule expression, and control decisions rather than line counts
• do not miss ad hoc fixes or workaround-shaped structure
• optimize first for faster, better human judgment
• treat improvement direction and Leave It Better as useful supporting lenses, not the main goal every time

Main Deliverables

The skill’s primary value is in these four outputs:

• target selection: identify where human attention should go first
• concern extraction: translate diffs into design-review concerns
• question framing: make explicit what the reviewer should verify
• next-action guidance: suggest deeper inspection, comparison, consultation, acceptance, or follow-up cleanup

Supporting Lenses

The following lenses are useful, but they are not the main job of the skill. Use them only when they help the human make a design judgment faster.

• design fidelity: whether rules and control logic are expressed in the intended responsibility and boundary structure
• structural validity: whether placement, dependency direction, and responsibility split make sense
• direction of change: whether the change moved the structure in a better or worse direction
• workaround risk: whether the change hardens ad hoc branches, local patches, or responsibility leakage
• KISS: whether unnecessary complexity or abstraction was introduced
• understandability: whether a human can still locate the key decisions easily
• changeability: whether the next similar change will be easier, not harder

Do not use these as a separate generic quality checklist. Use them only as supporting lenses for faster human design review.

Visualization

Visualization is not for making a diff look nicer. In most cases a short ranked handoff is enough. Use visualization only when:

• review exploration cost is high
• reviewers need to split work
• structural drift or rule drift is easier to communicate at a glance

Use it only when it helps answer where meaning changed, where design judgment matters, where ad hoc handling appeared, or what can safely be skimmed.

Workflow

Follow this sequence:

1. Gather the review inputs. 2. Decide whether this request is a fit for the skill. 3. Frame what the human reviewer actually needs to judge. 4. Find the business logic, core decision logic, and system-critical control logic hotspots. 5. Translate those hotspots into design-review concerns. 6. Produce review-supporting views and recommended reviewer actions. 7. Add visualization only if it helps materially. 8. Produce the review handoff.

1. Gather The Review Inputs

To keep the process reproducible, confirm these inputs first:

• target diff: what change is being reviewed
• base: what the diff is relative to
• spec sources: PR text, design memo, ADR, issue, existing rule documentation, or other intent sources
• exclusions: generated files, vendor code, snapshots, or other low-value review areas
• gap handling: whether missing information should be carried as an explicit assumption, downgraded confidence, or a weaker application of the skill

When possible, summarize this as a short review artifact contract:

• diff
• base
• spec sources
• exclusions
• known gaps

If inputs are missing, do not pretend to have higher confidence than the evidence supports. Carry the missing information forward explicitly.

For a concrete example, read references/input-collection-example.md.

2. Decide Whether This Request Fits The Skill

First determine whether this skill should be foregrounded.

Good fit examples:

• the diff is large enough that reading everything closely is expensive
• the change contains business logic, core decision logic, permission logic, contract boundaries, state transitions, or system-critical control decisions
• ad hoc fixes or workaround-shaped structure may be present
• bad time allocation would likely cause the reviewer to miss the important areas

Poor fit examples:

• the diff is small enough that full reading is practical
• the change is mostly style, lint, mechanical rename, or generated output
• the main subject is a local fix rather than core decision logic

When in doubt, use this simple rule:

• full application: the main subject includes business rules, responsibility placement, state transitions, contract change, permission logic, or system-critical control decisions, and target selection is more valuable than close-reading everything
• light application: there are design concerns, but the diff is only medium-sized and ordering the review is more important than a full structured handoff
• not a fit: design concerns are thin and a normal review or short diff summary is enough

If the request is not a fit, do not force core-logic concerns into it.

Standard output when it is not a fit:

• not a fit: why the skill is not a good fit
• suggested fallback: normal review, short diff summary, or another skill if appropriate
• lightweight output: optionally return only a short summary of the change

3. Frame What The Reviewer Needs To Judge

Define the design-review focus briefly. Do not try to conclude correctness here; align the review focus instead.

• which business rules, core decision logic, or system-critical control decisions changed
• which responsibility placements or rule expressions look likely to matter
• whether the central question is correctness, responsibility placement, or workaround-shaped handling

Assume the reviewer does not want a prettier diff. They want the shortest path to the design judgments that matter.

4. Find The Hotspots

Prioritize areas such as:

• changed branching, special-case handling, or guard logic
• changed states, lifecycle handling, visibility, permissions, charging, allocation, or other rules
• changed failure handling, retry, compensation, fallback, or recovery behavior
• changed API contracts, schema boundaries, event payloads, or permission boundaries
• changed decision placement, or logic forced into the wrong layer without structural cleanup

Read references/core-logic-signals.md when useful.

5. Translate Hotspots Into Design Concerns

Sort findings into these four review buckets:

• review deeply: design judgment is central, or the change touches rules, core decision logic, system-critical control logic, responsibility placement, state transitions, or contracts
• review if needed: orchestration, non-trivial refactors, test changes that imply intent changes, or wiring near important boundaries
• safe to skim: mechanical edits, shallow wiring, behavior-preserving renames, generated refreshes
• delegate to automation: lint, codegen, import order, static checks, and other changes with no semantic difference

Useful ambiguous examples:

• moving logic from controller to service may be review deeply or review if needed depending on whether decision placement actually improved
• large test-only changes may be review if needed if they imply changed intent, or safe to skim if they are only follow-up updates
• helper extraction with fewer lines may still be review deeply if it obscures decision placement
• a new flag used as a local fix may be review deeply if it sidesteps proper state or exception design

Every review deeply hotspot must have an explicit reason. Anchor it in at least one of these:

• likely mismatch between intended design and implementation shape
• suspicious placement of decision logic
• workaround-shaped handling
• unstable decision placement or responsibility boundaries
• high damage if wrong

Read references/review-target-prioritization.md and references/workaround-smells.md when needed.

Translate from diff-language into design-review language. For example:

• not “this diff is large,” but “this responsibility placement is the issue”
• not “more branching was added,” but “this rule expression is the issue”
• not “this looks complicated,” but “this special-case handling may be a workaround rather than a proper extension”

Each hotspot should include at least these eight items:

• target: what to inspect
• location: where in the code the change lives
• evidence: which concrete diff facts support the concern
• concern: why it is a design-review concern
• priority reason: why it belongs in this review bucket
• view: the skill’s concern or hypothesis
• question: what the human should verify
• recommended action: what to do next

Granularity rules:

• review deeply must include all eight items
• review if needed must include at least target / location / evidence / concern / priority reason / question, with view and recommended action added when useful
• safe to skim and delegate to automation can be grouped

evidence must contain at least one concrete diff fact.

• a concrete changed condition, field, status, branch, retry rule, permission edge, payload change, or other diff fact

Do not use a file name or function name alone as evidence. Those belong in location.

6. Produce Review-Supporting Views And Actions

Views are not final judgments. They are review hypotheses meant to speed up human review.

How to write them:

• avoid false certainty
• make the concern or structural discomfort explicit
• do not assume the intended design if the evidence does not show it
• tie the view to the actual concern in the diff
• do not invent claims beyond the evidence

Recommended actions should lead naturally to a next step. Typical actions:

• inspect deeply: read code and design sources together
• check against design sources: compare with ADRs, design memos, or existing rules
• consult a domain owner: confirm rule intent or exception behavior
• accept for now: explicitly accept the risk and record follow-up if needed
• suggest small follow-up cleanup: propose a bounded cleanup inside the changed area

Use direction of change only as an extra lens when needed, especially if decision placement became clearer or if workaround hardening is a concern.

7. Add Visualization Only If It Helps

Visualization is a supporting tool. If you use it, prefer one view and add a second only when it clearly changes reviewer behavior.

Pattern A: Structure Drift View

Use when the main need is to show where responsibility placement or dependency direction drifted.

Show:

• where decision logic now lives
• where logic escaped its proper responsibility
• where dependency reversal or boundary crossing appears

Pattern B: Rule Fidelity View

Use when the main need is to show changed rule or state expression.

Show:

• changed rules or workflow steps
• branch, state-transition, or failure-path changes
• missing, duplicated, or patched-on rule handling

Pattern C: Direction View

Use only as a supporting view when the reviewer needs help deciding whether decision placement became clearer or workaround hardening increased.

Show:

• improved / neutral / regressed
• places where decision placement became clearer
• places where ad hoc structure was hardened

Read the visualization section in references/review-handoff-format.md when useful.

8. Produce The Review Handoff

Use this structure:

• review artifact contract: diff, base, spec sources, exclusions, known gaps
• review target selection: grouped by review deeply / review if needed / safe to skim / delegate to automation
• extracted design concerns
• agent view
• recommended reviewer action
• optional visualization

Output limits:

• review deeply: at most 3 items
• review if needed: at most 5 items
• safe to skim: grouping allowed
• delegate to automation: grouping allowed

When the limit would be exceeded, group rather than enumerate everything.

Read references/review-handoff-format.md when useful.

For contrastive examples of good and weak handoffs, read references/handoff-examples.md.

Output Rules

• do not give every changed area equal weight
• always pair what to inspect with why it matters
• tie concerns to business meaning, structural meaning, or control meaning
• do not say only “this looks complex”; say what makes reasoning or future change harder
• make the reviewer’s next step explicit
• include at least one evidence item for every hotspot
• include a priority reason for every hotspot
• if you recommend visualization, explain how it speeds judgment
• state uncertainty explicitly when confidence is limited

Watch Outs

• do not treat large files as automatically high value
• do not give generated or mechanical changes the same weight as design-relevant changes
• do not miss structural regressions just because the code “works”
• do not mistake extra abstraction for better design
• do not call helper extraction alone an improvement
• do not demand full redesigns for every change
• do not make direction of change the main point every time

Self-Check

Before responding, confirm:

• the design-review focus is clear
• the request is actually a fit for the skill
• the review artifact contract is present
• the hotspots in business logic, core decision logic, and system-critical control logic were actually extracted
• every deep-review hotspot has a design reason
• the four review buckets are preserved in the final output
• the item limits are respected
• every hotspot has evidence
• every hotspot has priority reason
• every hotspot includes a reviewer question
• the views support human judgment instead of replacing it
• the recommended actions lead to real next steps
• workaround signals were actually considered
• supporting lenses such as KISS, understandability, and changeability were used only when helpful
• direction of change was used only when it truly helped
• any visualization is judgment-supporting rather than decorative

core-logic-review-prioritizer

このスキルは何か

大きな変更の中から、業務ロジックや中核の判断ロジックに関わるレビュー対象を優先づけるためのスキルです。

作った意図

大きな diff を前にすると、全部を同じ濃さで読むことが難しくなり、本当に危ない判断変更よりも表面的な差分に時間を使ってしまいがちです。このスキルは、そうしたレビューの時間配分ミスを減らし、人が設計判断を向けるべき場所を先に浮かび上がらせるために作っています。

特に、業務ルール、責務配置、状態遷移、権限境界、契約変更のように、間違えると後から効く論点を見逃しにくくしたい意図があります。

どういう人・場面に向いているか

• AI が作った大きめのコード変更をレビューする人
• 重要なロジック変更を含む diff を短時間で見切る必要がある人
• 「全部読む」より「深く読む場所を絞る」ほうが価値の高いレビューをしたい人

使いどころの例

• 決済、権限、在庫、申請承認のような重要ロジックを含む大きな PR をレビューしたい
• リファクタリングに見えるが、実は判断ロジックの置き場所がずれていないか確認したい
• AI が作った変更のうち、どこを人間が重点的に見るべきか整理したい

依頼イメージ

入力例: 「この大きめの PR で、人が深く見るべき業務ロジック変更を絞って。特に権限判定と状態遷移まわりが気になっている」

返ってくるもの: 「どこを重点レビューすべきか」「なぜそこが危ないか」「人が確認すべき問い」を優先順に整理したレビューの下ごしらえ

関連するスキル

• review-orchestrator: 観点を揃えて広くレビューしたいときに向いています
• software-design-review-router: diff 単位というより、設計判断そのものを評価したいときに向いています

Signals Of Core Decision Logic

Treat a change as likely business logic, core decision logic, or system-critical control logic when one or more of the following are true:

• branching changes who gets what outcome
• thresholds, caps, pricing, eligibility, ranking, scoring, or allocation rules change
• state transitions or lifecycle handling change
• validation or exception rules change
• rules for inventory, reservation, settlement, approval, publishing, aggregation, or reconciliation change
• permission, visibility, or approval decisions change
• the meaning of idempotency, deduplication, ordering, or retry changes
• externally meaningful value conversion or rounding changes
• privilege-escalation paths, authorization-cache invalidation boundaries, or session boundaries change
• queue order, backpressure handling, replay conditions, or failover decisions change
• feature-flag targeting semantics or application conditions change
• audit-event, trace, or alert emission conditions change or disappear
• control decisions for delivery, job execution, or consistency preservation change

Signals with especially high human-review value:

• new if, switch, guard, or special-case branches
• changed handling per enum or status
• changed default-case or fallback behavior
• changed timeout, retry, rollback, or compensation handling
• changed authorization paths, failover paths, or queue admission conditions
• changed feature-flag conditions, audit-output conditions, or cache invalidation rules
• removed or loosened constraints
• added special handling per customer type, plan, region, or role

Signals with relatively low manual-review value:

• import-only cleanup
• formatting-only changes
• generated-file refresh only
• renames with behavior preserved by tests
• shallow wiring with no added semantic branching

Handoff Examples

Use these examples to keep the final handoff concrete and compact.

Good Handoff

review target selection

• review deeply
• renewal_state_machine.ts
• priority reason: state-transition meaning changed and failure impact is high
• review if needed
• billing_retry_worker.ts
• priority reason: retry placement may have shifted, but evidence of semantic change is limited
• safe to skim
• UI copy updates in billing settings
• delegate to automation
• regenerated GraphQL types

extracted design concerns

• the new past_due transition may shift permission and retry behavior
• retry ownership may now be split between the worker and the service

agent view

• the diff suggests clearer state naming, but decision ownership around retry still looks unstable

recommended reviewer action

• compare past_due behavior against the billing ADR
• confirm with the domain owner whether retry is supposed to remain worker-owned

Why this is good:

• attention is clearly limited
• every deep item has a reason
• the reviewer gets concrete next steps

Weak Handoff

review target selection

• many files changed in billing
• controller, service, worker, tests, and events all touched

agent view

• this looks complex and risky

recommended reviewer action

• review carefully

Why this is weak:

• no prioritization
• no evidence-backed concern
• no reviewer question
• no actionable next step

Input Collection Example

Use a lightweight collection pattern before reviewing.

Example

review artifact contract

• diff: PR #482 against main
• base: origin/main
• spec sources: PR description, docs/billing-renewal.md, ADR-019, linked issue BILL-241
• exclusions: generated/, snapshots, dependency lockfile refresh
• known gaps: no downstream consumer list for the new billing event

Minimal Command Pattern

Adapt to the repo, but a typical collection flow looks like:

• identify the diff range or PR number
• identify the base branch
• identify design-intent sources such as PR text, ADRs, or issues
• exclude generated or mechanical-change areas before hotspot selection

Bad Collection Pattern

Avoid starting with only:

• a raw diff with no base reference
• no design-intent source
• generated files mixed into hotspot selection
• no explicit record of missing information

Review Handoff Format

The handoff should be short, ranked, and immediately usable by a human reviewer.

Base Template

review artifact contract

• diff
• base
• spec sources
• exclusions
• known gaps

review target selection

• review deeply
• review if needed
• safe to skim
• delegate to automation
• why those priorities were chosen
• each hotspot’s priority reason

extracted design concerns

• which responsibility placements are under question
• which business-rule, control-decision, state-transition, or contract-boundary expressions are under question
• which workaround smells are under question

agent view

• the skill’s concerns or hypotheses
• written as review support, not as a final verdict

recommended reviewer action

• what the human should verify next
• who may need to be consulted
• whether the likely next step is accept, hold, or follow-up cleanup

optional visualization

• only when useful
• explain which judgment it helps accelerate

Count Limits

• review deeply: at most 3 items
• review if needed: at most 5 items
• safe to skim: grouping is allowed
• delegate to automation: grouping is allowed

If the list would exceed these limits, group instead of enumerating everything.

Minimum Fields Per Hotspot

• target: what to inspect
• location: file, function, or responsibility unit
• evidence: which concrete diff fact supports the concern
• concern: what the design concern is
• priority reason: why it belongs in this review bucket
• view: the skill’s concern or hypothesis
• question: what the human should verify
• recommended action: what to do next

evidence must include at least one concrete diff fact.

• a concrete changed condition, state, branch, field, retry rule, permission edge, payload change, or similar diff fact

Do not use a file name or function name alone as evidence. Those belong in location.

When To Use Visualization

Visualization is a support tool. In most cases, a ranked table or concise handoff is enough.

Use it when:

• exploration cost is high
• multiple reviewers need to coordinate
• structural drift or rule drift is easier to understand at a glance

Structure Drift View

Recommended template:

Rule Fidelity View

Recommended template:

Direction View

Recommended template:

Writing Guidance

• prefer short ranked bullets over long summaries
• give business, structural, or control meaning where possible
• state uncertainty when it exists
• make the next action obvious
• avoid claims not supported by evidence

Review Target Prioritization

Use this file to decide where human attention should go first.

The purpose is not generic risk scoring. The purpose is to push scarce human review time toward changes that require design judgment in business logic, core decision logic, or system-critical control logic.

Patterns That Raise Priority

Changes matching the following patterns should usually land in review deeply or review if needed.

State And Workflow

• new states or statuses are introduced
• terminal-state or cancellation handling changes
• fail-fast versus retry policy changes
• asynchronous ordering or timing changes

Contracts And Boundaries

• API field meaning changes
• schema nullability, defaults, uniqueness, or ownership changes
• event payload changes may affect downstream consumers
• permission boundaries or tenant boundaries change

System-Critical Control Decisions

• authorization-cache invalidation boundaries change
• job replay, redelivery, or resume conditions change
• queue ordering or backpressure handling changes
• failover, degrade, or fallback decision conditions change
• feature-flag targeting semantics change
• audit-event, trace, or alert emission conditions change

Business Damage Risk

• rules touching money, discounts, billing, credit, or quotas change
• rules touching inventory, reservation, seats, or capacity change
• rules touching publishing, approval, moderation, or visibility change
• changes affect auditability, traceability, or compliance behavior

AI-Assisted Change Patterns Worth Watching

• the change is broad but tests are weak
• many files changed but the semantic core is poorly explained
• the same conditional logic is duplicated across layers
• helper extraction makes decision ownership harder to see
• abstraction was introduced for what still looks like a one-off case
• authorization, retry, auditing, or consistency decisions are split across multiple places

Using The Four Buckets

To reduce subjectivity, check each hotspot briefly on these four axes:

• impact size: how painful it would be if this is wrong
• semantic change likelihood: whether business meaning or system meaning may have changed
• responsibility-boundary impact: whether ownership or boundary placement is unstable
• evidence strength: whether the concern is supported by concrete diff evidence

Strict scoring is not required, but classification should follow these simple rules and include at least one short classification reason.

• review deeply: impact size or semantic change likelihood is high, and evidence strength is sufficient
• review deeply: responsibility-boundary impact is high, and evidence strength is sufficient
• review if needed: semantic change likelihood or responsibility-boundary impact is present, but impact size or evidence strength is limited
• safe to skim: semantic change likelihood is low and responsibility-boundary impact is also low
• delegate to automation: semantic change likelihood is absent and the change is mostly mechanical

review deeply

Use this when any of the following is true:

• the design judgment itself is central to the change
• rules or state transitions change
• responsibility placement or decision ownership is unstable
• workaround smell is strong
• the damage if wrong is high

review if needed

Use this when any of the following is true:

• the area is not the main concern, but design implications are present
• orchestration or wiring changes touch responsibility boundaries
• test changes imply intent changes
• refactoring affects how visible the core decision logic is

safe to skim

Use this when any of the following is true:

• the change is mostly mechanical
• wiring is shallow and semantics are unlikely to change
• the change is mostly rename or follow-up adjustment

delegate to automation

Use this when any of the following is true:

• lint, format, or import ordering only
• code generation refresh
• snapshot churn without semantic difference

How To Write Priority Reasons

Whenever you assign a bucket, try to explain it in this shape:

• what changed
• why human review matters
• which bucket it belongs in
• priority reason

Examples:

• A new past_due state was introduced and may affect permission handling, so this belongs in review deeply.
• The authorization-cache invalidation boundary changed, and the possible blast radius for over-permission or over-denial is high, so this belongs in review deeply.
• This looks like a controller-to-service move only, but it is worth checking whether decision ownership actually improved, so this belongs in review if needed.
• Only GraphQL type regeneration changed, so this belongs in delegate to automation.

Short priority-reason examples:

• High impact and likely semantic change.
• Semantic change seems limited, but boundary placement is affected.

Workaround Smell Signals

AI-assisted changes often produce code that works locally but degrades structure globally. Use this file to look for those cases.

Common Signals

• the same decision logic is duplicated across multiple layers
• special-case handling is placed outside its natural responsibility
• helper extraction happened, but the real business or control decision became harder to locate
• only the exception path was patched locally, without re-shaping the overall rule
• states or flags increased, but the overall transition model was not cleaned up
• a one-off condition is hidden behind abstraction
• names or comments suggest temporary, workaround, fallback, or quick fix
• authorization decisions are duplicated in multiple places
• retry or replay conditions are distributed across several components
• consistency problems are hidden behind feature flags or temporary flags
• audit events or traces are missing only on failure paths
• fallback or failover decisions are scattered across responsibility boundaries
• control decisions are split across jobs, workers, services, and controllers

Reviewer Questions

• where should this decision naturally live
• is the same rule written again somewhere else
• is this exception handling a real rule extension or just patchwork
• will the next similar change be easier after this one
• is the touched area easier to understand than before
• can this authorization or control decision be explained from one place
• are failure handling and retry handling split into a separate path for no good reason
• are auditing, tracing, or notification split between normal and failure flows

Things Commonly Mistaken For Improvement

• helper extraction only
• adding interfaces only
• “preparing for future extensibility” when the code really just hides a one-off condition
• fewer lines of code, but less visible decision ownership