skill: refine repo-review skill instructions for clarity and calibration

.agents/skills/mygo-api-repo-review/SKILL.md

@@ -5,7 +5,7 @@ description: Review the MyGO backend repository for material, evidence-backed ar
 
 # MyGO API Repository Review
 
-Perform a read-only, evidence-first review of the MyGO backend. Find real defects and systemic risks without manufacturing findings from stylistic preferences, unsupported hypotheticals, or intentional design choices.
+Perform a read-only, evidence-first review of the MyGO backend. Find material defects and systemic risks without turning unfinished product scope, stylistic preferences, or unsupported hypotheticals into findings.
 
 ## Resolve the review scope
 
@@ -32,29 +32,20 @@ Keep the review read-only unless the user separately asks for fixes.
 3. Do not fetch, pull, commit, stage, or discard changes.
 4. Capture Git status again before reporting. If the workspace changed, identify the change and do not erase it.
 
-## Establish context
+## Review the implementation
 
 Read `AGENTS.md`, `docs/roadmap.md`, `docs/architecture.md`, `docs/decisions.md`, and `docs/development.md` before judging the implementation. Treat documented decisions as intent, not as proof that their implementation is correct.
 
-Map the reviewed packages, dependency direction, public entry points, state owners, external resources, and important lifecycle operations. Use `rg` and targeted file reads; do not read `go.sum` in full.
+Apply production-grade correctness, security, resilience, and architecture standards to behavior and components that already exist, including implemented paths within WIP features. Do not interpret that standard as requiring every capability of the finished product to exist now.
 
-## Review objective
+1. Map the reviewed packages, dependency direction, entry points, state owners, external resources, and lifecycle operations. Use `rg` and targeted reads; do not read `go.sum` in full.
+2. Reconstruct behavior, boundaries, invariants, state transitions, and trust assumptions from code, tests, configuration, and documentation.
+3. Trace important control, data, ownership, resource, concurrency, and failure flows without starting from a predetermined bug list.
+4. Use the lenses below for minimum coverage, then challenge every candidate before reporting it.
 
-Find material, evidence-backed flaws in the repository's architecture, design, and implementation. Prioritize problems that can meaningfully harm correctness, security, resilience, data integrity, scalability, extensibility, decoupling, customizability, or maintainability. Favor systemic causes and cross-component interactions over local code smells.
+Treat the lenses as perspectives, not an exhaustive checklist, taxonomy, or finding quota:
 
-Do not begin from a predetermined list of expected bugs. Reconstruct intended behavior, boundaries, invariants, state transitions, and trust assumptions from code, tests, configuration, architecture documentation, technical decisions, and the roadmap.
-
-## Analyze in phases
-
-1. Build a working system model before producing findings.
-2. Perform an open-ended pass by tracing important control, data, state, ownership, resource, and failure flows across component boundaries.
-3. Perform a coverage pass using the review lenses below.
-4. Challenge each candidate by seeking evidence that the behavior is intentional, unreachable, contained, or already protected.
-5. Classify and report findings only after discovery and falsification.
-
-Treat these lenses as minimum coverage, not as an exhaustive checklist, required taxonomy, or finding quota:
-
-- **Architecture and evolution:** Evaluate whether responsibilities, dependencies, boundaries, data flows, or resource use create material obstacles to supported behavior, realistic scaling, roadmap work, extensibility, decoupling, customization, or maintenance.
+- **Architecture and evolution:** Evaluate whether responsibilities, dependencies, boundaries, data flows, or resource use materially obstruct supported behavior, scaling, committed evolution, extensibility, decoupling, customization, or maintenance.
 - **Security:** Evaluate whether trust, identity, authorization, ownership, confidentiality, integrity, availability, or exposure assumptions can be violated through a reachable execution path or component interaction.
 - **Resilience:** Evaluate whether plausible partial failures, dependency failures, cancellation, concurrency, malformed inputs, or interrupted lifecycle operations can cause disproportionate impact, cascading failure, loss of service, or an unrecoverable state.
 - **Data consistency:** Evaluate whether persistent state, external resources, ownership, and lifecycle transitions preserve required invariants across normal, concurrent, retried, interrupted, and partially failed execution paths.
@@ -67,7 +58,7 @@ Keep small `diff` and narrowly targeted reviews in the main agent by default. Fo
 
 Give every reviewer the complete, non-exhaustive review objective and one primary emphasis such as architecture and performance, security, or resilience and data consistency. Make the emphasis a starting perspective rather than an exclusive boundary. Wait for all reviewers, then independently verify, deduplicate, and rank their candidates in the main agent.
 
-## Verify deterministically
+## Verify and report
 
 Run the repository-wide checks below unless the user explicitly limits command execution or the environment prevents them:
 
@@ -76,10 +67,6 @@ Run the repository-wide checks below unless the user explicitly limits command e
 - `go test ./...`
 - a non-mutating `gofmt -l` check over tracked Go files
 
-Record each check and its result. When a test fails, inspect the test first and follow the debugging principles in `AGENTS.md`. Do not convert a command failure into an architecture finding without validating its cause. Put checks that cannot run and their reasons under `Unverified areas`.
+Record each check and its result. When a test fails, inspect the test first and follow the debugging principles in `AGENTS.md`. Do not convert a command failure into an architecture finding without validating its cause.
 
-## Filter and report
-
-After discovering candidate findings, read [review-calibration.md](references/review-calibration.md) and apply its evidence and falsification rules. Before writing the final response, read [report-template.md](references/report-template.md) and follow it exactly.
-
-Report a candidate only when another developer can verify its location, causal path, and material impact. Place unresolved hypotheses under `Unverified areas` with the evidence needed to resolve them. If no candidate qualifies, state `Findings: None` rather than lowering the threshold.
+After open-ended discovery, read [review-calibration.md](references/review-calibration.md) and apply its admission and falsification rules. Then read [report-template.md](references/report-template.md) and follow it exactly. If no candidate qualifies, state `Findings: None` rather than lowering the threshold.

.agents/skills/mygo-api-repo-review/references/report-template.md

@@ -22,6 +22,8 @@ Use these severity levels independently of category:
 
 Sort findings by severity, then by impact within the same severity. Security is a category, not a severity; a security finding can have any severity.
 
+Make each `Analysis` identify the existing behavior, boundary, or invariant under review, the evidence and reachable violation path, and the material impact. Do not use any report section as a backlog for absent WIP, planned, or future capabilities.
+
 Use this structure:
 
 ```markdown
@@ -34,19 +36,22 @@ Use this structure:
 
 - Findings
   - ID: <CATEGORY-NNN>
-  - Severity: Critical | High | Medium | Low
-  - Location: <filename:line>
-  - Analysis: <evidence, reachable causal path, and material impact>
-  - Recommendation: <root-cause repair direction>
+    - Severity: Critical | High | Medium | Low
+    - Location: <filename:line>
+    - Analysis: <existing behavior or invariant, evidence and reachable violation path, and material impact>
+    - Recommendation: <root-cause repair direction>
+
+  - ID: <CATEGORY-NNN>
+    - <same as above>
 
 - Architecture drift
-  - <material differences between documented and implemented architecture, referencing finding IDs instead of duplicating analysis>
+  - <material current differences between documented and implemented architecture, referencing finding IDs instead of duplicating analysis>
 
 - Documentation drift
   - <documentation inaccuracies that can materially mislead implementation, operation, or review>
 
 - Unverified areas
-  - <unverified area, reason, and required validation>
+  - <near-qualifying current defect, missing fact, and the specific validation needed>
 ```
 
 If there are no qualifying findings, write `Findings: None`. Write `None` for any other empty section. Do not omit verification failures or review limitations.

.agents/skills/mygo-api-repo-review/references/review-calibration.md

@@ -1,27 +1,27 @@
 # Review Calibration
 
-Use this reference only after the open-ended discovery pass. Apply it to challenge candidate findings and suppress false positives.
+Use this reference only after open-ended discovery. Apply it to decide which candidates deserve a place in the report.
 
-## Finding eligibility
+## Admit a finding
 
-Accept a candidate as a finding only when all of these are present:
+Accept a candidate only when all of these are present:
 
-- Concrete evidence in current code or documented design.
-- A violated invariant or reachable, plausible failure scenario.
-- A material consequence under supported behavior or realistic roadmap use.
-- A precise source location that lets another developer verify the analysis.
-- A recommendation that addresses the underlying cause.
+- An existing implemented behavior, boundary, or intrinsic invariant, including code already exposed within a WIP feature. An absent part of a WIP, planned, or future capability is not itself a basis.
+- Concrete evidence that current code violates that behavior or invariant through a reachable, plausible path.
+- A material consequence under production-grade operation of the existing capability, without requiring the finished product's full feature set.
+- A precise source location and a recommendation that primarily corrects existing behavior or structure rather than delivers a missing product capability.
 
-Actively seek the strongest disconfirming evidence before accepting a candidate. Check whether another layer enforces the invariant, the path is unreachable, the behavior is explicitly unsupported, or the tradeoff is intentional and adequately contained.
+Ask: **Does the repair mainly correct existing behavior, or design and deliver a capability that does not yet exist?** The amount of code required is not decisive; the repair's purpose is.
 
-## Calibration rules
+Seek the strongest disconfirming evidence. Check other layers, tests, supported scope, containment, and intentional tradeoffs before accepting a candidate.
 
-- Do not report a missing abstraction, restriction, validation, limit, test, or defensive mechanism solely because it is absent. Demonstrate the failure path or violated invariant caused by the absence.
-- Do not treat a permissive configuration or documented tradeoff as a problem by itself. Report it only when a supported setting bypasses required processing or breaks security, lifecycle, or consistency invariants.
-- Do not treat a simple implementation as an architecture flaw without concrete coupling, duplicated responsibility, boundary leakage, unsafe change propagation, or realistic scaling impact.
-- Do not report theoretical performance limits without a reachable hot path, resource-growth mechanism, and material consequence under realistic use or roadmap requirements.
-- Do not report style preferences, naming preferences, speculative future features, or optional hardening as defects.
-- Do not weaken or reinterpret a valid test to remove an implementation failure. Confirm intended behavior before deciding whether the test or implementation is wrong.
-- Do not duplicate one root cause across review lenses. Assign one primary category and describe secondary impacts in its analysis.
+## Apply the boundary
 
-Place credible concerns that lack required evidence in `Unverified areas`. State what is unknown, why it matters, and the smallest validation needed to resolve it.
+- A missing safeguard qualifies only when it is intrinsic to an existing interface or mechanism and its absence creates a demonstrated failure. Do not turn expected product policies or lifecycle subsystems into defects merely because a mature product will need them.
+- For configuration, distinguish enforceable technical validity from operator judgment. Report values that violate an implemented mechanism's objective preconditions or are silently misapplied; do not claim the program can prove secret entropy or prevent every poor but technically valid policy choice.
+- Report architecture or evolution risk only when current design causes concrete coupling, boundary leakage, unsafe change propagation, or material rework for a committed direction. A missing future subsystem is not an architecture flaw.
+- Require a reachable hot path, resource-growth mechanism, and material impact for performance findings. Do not report style, naming, speculative scale, or optional preference as a defect.
+- Keep one primary violated invariant and root cause per finding. Do not combine independent missing defenses to raise severity; assign one category and describe only supported secondary impacts.
+- Preserve valid tests and intended behavior. Never weaken a test to dismiss an implementation failure.
+
+Use `Unverified areas` only for a near-qualifying current defect that a specific factual check can resolve. Omit undecided product policy, future capability, and general hardening ideas rather than using this section as a backlog.