[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C7F9CFB97ZKCYC5B0J2TJQ":3,"skill-same:01M6C7F9CFB97ZKCYC5B0J2TJQ":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":27,"linkOnly":28,"markdownContent":29,"markdownBody":30,"frontMatter":31,"refName":32,"commitSha":33,"skillDirectory":34,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":6,"ownerHtmlUrl":37,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":38,"install":39,"resources":52},"01M6C7F9CFB97ZKCYC5B0J2TJQ","kspec-review",null,"How to review work and use kspec review records. Covers both reviewer and worker perspectives — creating reviews, structuring findings, AC coverage verification, review principles, and the full review record interface.","lepahc\u002Fkynetic-spec","lepahc","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F255431765?v=4","01M6C7E6Z0C8SE1X6PJ2F9Q1CX","01M6C7E744QKNYBVZ7KV7Z69GF",1,"MIT","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkspec-review\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26],"review","kspec review","verification","how","reviewer","work","perspectives","coverage","use","2026-11-10 10:12:30",false,"---\nname: kspec-review\ndescription: How to review work and use kspec review records. Covers both\n  reviewer and worker perspectives — creating reviews, structuring findings, AC\n  coverage verification, review principles, and the full review record\n  interface.\n---\n\u003C!-- kspec-managed -->\n# Review\n\nHow to review work and use kspec review records. Covers creating reviews, structuring findings, AC coverage verification, and the full review record interface.\n\n## When to Use\n\n- Reviewing submitted work\n- Creating or managing review records\n- Verifying AC coverage\n\n## Review Principles\n\n### Adversarial Investigation\n\n**Worker claims are hypotheses, not facts.** When a commit message says \"all tests pass,\" verify it. When a note says \"fixed the type errors,\" check they're actually fixed and not suppressed. Workers are not lying — but they are biased toward believing their own work is correct. Your job is to independently verify.\n\n**Read the code before the description.** Start by reading the diff — what changed, what was added, what was removed. Form your own understanding. Only then read the task notes or PR description and compare. This prevents anchoring bias.\n\n**Treat justifications as claims to verify.** \"Pre-existing issue,\" \"out of scope,\" \"will be addressed in follow-up,\" \"this is the standard pattern\" — these require evidence, not acceptance.\n\n**A clean review is valid.** Not every submission has bugs. If you investigate thoroughly and find nothing wrong, approve. Do not invent findings to justify time spent. The goal is accuracy, not a finding quota.\n\n### Cognitive Biases to Counteract\n\n**Satisfaction of search** — After finding the first issue, your detection rate drops 25-50%. Finding one issue makes it MORE likely there are others. Deliberately increase scrutiny after your first finding.\n\n**Complexity bias** — Simple-looking changes (renames, test rewrites, config changes) receive less scrutiny because they \"look safe.\" These are where semantic bugs hide. Every submission gets the same investigation depth.\n\n**Anchoring** — Don't frame analysis around the author's stated intent. Assess what the code actually does, not what the author says it does.\n\n**Decision fatigue** — On the Nth review, reviewers default to approval. Every approval must be backed by specific evidence of verification.\n\n### Structured Exploration\n\nBefore rendering any verdict, complete both deterministic and analytical checks:\n\n**Deterministic checks** (run these, don't reason about them):\n\n```bash\nkspec item get @spec-ref                    # Own ACs + inherited trait ACs\nkspec validate --refs --warnings-ok         # Reference\u002Fschema sanity\nkspec validate --alignment --warnings-ok    # Spec\u002Ftask alignment baseline\nkspec validate --completeness --warnings-ok # AC coverage baseline\n\n# Run the project-defined quality gates (format \u002F lint \u002F type \u002F test, plus any\n# focused changed-file gates). The concrete commands are named in your\n# project's quality-gate guidance — do not assume a toolchain.\n\n# Confirm AC annotations exist for the spec and any inherited traits using\n# whatever search tool fits the project's test layout.\n```\n\nProject-defined gate failures are review blockers. Request changes rather than approving when these gates are red or missing without a documented reason. If repo-wide lint has a warning baseline, changed-file lint warnings are still review findings unless you verify they are pre-existing outside the submitted diff.\n\n**Analytical checks** (require reading and judgment):\n\n1. Read the diff — every changed file, not just the interesting ones\n2. Read surrounding context — unchanged files that interact with changed code\n3. Verify spec alignment — for each AC, confirm the code satisfies the behavior\n4. Verify at least one worker claim independently\n5. Search across categories — correctness, edge cases, error handling, security, test quality, integration\n\n**Complete ALL checks before recording any verdict.** Do not stop at the first finding. Each unrecorded finding becomes a future fix cycle that could have been avoided. Record every issue you find, then submit one verdict covering all of them.\n\n**Verify findings are real, not invented.** Every finding must be backed by evidence you can demonstrate — code you read, tests you ran, commands you executed. Run the test suite. If an AC implies edge case behavior (concurrency, boundary values, error paths), check whether tests actually cover those cases — missing edge case coverage is a must-fix. Do not emit findings based solely on reading code and reasoning about it; execute what you can to confirm.\n\n---\n\n## AC Coverage Verification\n\n### Own AC Coverage\n\nEvery acceptance criterion on the spec MUST have at least one annotated test.\n\n```bash\n# Get all ACs (own + inherited from traits)\nkspec item get @spec-ref\n\n# Search for annotations in test files using whatever search tool fits\n# the project's language and test layout.\n```\n\nAnnotations use language-appropriate comment syntax:\n\n```javascript\n\u002F\u002F AC: @spec-ref ac-1\nit('should validate input', () => { ... });\n```\n\n```python\n# AC: @spec-ref ac-1\ndef test_validates_input():\n    ...\n```\n\nBefore accepting coverage, confirm each annotation matches the AC text from `kspec item get` — not just the `ac-N` number. A test must actually prove the AC, not just touch the code path.\n\n### Trait AC Coverage\n\nWhen a spec implements traits, it inherits their ACs. Every inherited AC needs test coverage using the **trait's** ref:\n\n```javascript\n\u002F\u002F AC: @trait-json-output ac-1\nit('should output valid JSON with --json flag', () => { ... });\n```\n\n```bash\n# kspec validate reports uncovered trait ACs\nkspec validate\n```\n\nAny \"inherited trait AC(s) without test coverage\" warning is a blocker.\n\nIf a trait AC genuinely doesn't apply, annotate it with a reason:\n\n```javascript\n\u002F\u002F AC: @trait-json-output ac-3 — N\u002FA: this command has no tabular output\n```\n\nAnnotations must be standalone line comments, not embedded in block comments.\n\n### Source-Scanning Tests (Reject on Sight)\n\nAny test whose mechanism is reading implementation source files and asserting on their textual content is an automatic MUST-FIX — regardless of what AC it claims to cover, what language it's in, or how the file reading is accomplished. The technique is the problem, not the specific API used.\n\nThe test: \"does this source file contain this string?\" The answer tells you nothing about whether the feature works. These tests create the illusion of coverage while testing nothing, and they are the most common shortcut agents take when ACs are difficult to test behaviorally.\n\nWhen you encounter source-scanning tests, flag them as MUST-FIX with a request to replace with behavioral tests that exercise the system. If an AC genuinely cannot be tested by exercising behavior, that signals the AC needs revision — not that source scanning is acceptable.\n\n### Spec Alignment\n\nImplementation must match spec intent, not just pass tests:\n\n1. **Implementation exists** — Code handles the described behavior\n2. **Test exists** — A test validates the behavior\n3. **Behavior matches** — The test actually proves the AC, not just syntactically passes\n\n---\n\n## Review Records\n\nkspec stores first-party review records as durable artifacts in the shadow branch. They track the full lifecycle of reviewing work — threaded comments, check results, verdicts, and audit history.\n\n### Review Lifecycle\n\n```\ndraft → open → closed\n                 ↓\n              archived (terminal)\n```\n\n| State      | Meaning                                                           |\n| ---------- | ----------------------------------------------------------------- |\n| `draft`    | Review created but not yet started                                |\n| `open`     | Active review in progress                                         |\n| `closed`   | Review concluded (auto-closed on approve\u002Frequest_changes verdict) |\n| `archived` | Permanently archived                                              |\n\n**Auto-close on verdict:** When a reviewer submits an `approve` or `request_changes` verdict, the review record automatically transitions to `closed`. A `comment` verdict leaves the review open since it doesn't represent a final assessment. Each closed review is a point-in-time artifact.\n\n### Per-Cycle Review Model\n\nEach review cycle produces its own review record. Each review is a discrete artifact with its own verdict, and the collection of reviews across cycles comprises the full review history for the task.\n\n**How it works:**\n\n- When a task enters `pending_review`, the reviewer creates a **new** review record\n- If a prior closed review exists, it remains as a historical artifact\n- The task's `review_ref` is updated to point to the new record\n- Historical reviews are accessible via `kspec review for-task @ref` (returns all linked reviews)\n\n**Do NOT reopen old reviews.** Instead, create a fresh review for each cycle. This keeps each review's findings, verdict, and context self-contained.\n\n### Disposition (Computed)\n\nThe disposition is computed from verdicts, checks, and threads — not set directly:\n\n| Disposition         | Condition                                                                                                                                         |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pending`           | No verdicts, or only `comment` verdicts                                                                                                           |\n| `approved`          | At least one `approve` verdict matching current version, no blocking `request_changes`, all required gates passing, no unresolved blocker threads |\n| `changes_requested` | Any `request_changes` verdict matching current version, or required gates failing, or unresolved blocker threads                                  |\n\n### Creating Reviews\n\n```bash\n# Review a task (auto-links review_ref on the task)\nkspec review add --title \"Review task-add-auth\" \\\n  --subject-type task --subject-ref @task-add-auth\n\n# Review committed code (requires base\u002Fhead commits)\nkspec review add --title \"Review feature branch\" \\\n  --subject-type code --base abc1234 --head def5678 \\\n  --base-branch \u003Cproject-integration-branch> --head-branch \u003Cfeature-branch> \\\n  --related-ref @task-add-auth\n\n# Review a plan or spec\nkspec review add --title \"Review auth plan\" \\\n  --subject-type plan --subject-ref @plan-auth\n```\n\n**Subject types:** `task`, `code`, `plan`, `spec`, `external`\n\n### Structuring Findings as Threads\n\nEach finding becomes a thread with a kind that determines its impact:\n\n```bash\n# Blocker — must be resolved before approval\nkspec review comment @review-ref \\\n  --body \"Missing error handling for invalid input\" --kind blocker\n\n# Question — non-blocking, needs clarification\nkspec review comment @review-ref \\\n  --body \"Why was this approach chosen over X?\" --kind question\n\n# Nit — non-blocking, minor suggestion (default)\nkspec review comment @review-ref \\\n  --body \"Consider renaming this variable\" --kind nit\n```\n\n**Thread kinds:** `blocker` (blocks approval), `question` (non-blocking), `nit` (non-blocking, default).\n\nOnly blocker threads affect disposition. Unresolved nits and questions do not block approval.\n\n#### Code-Targeted Comments\n\n**Always anchor code findings to specific lines.** Use `--path`, `--line-start`, and `--line-end` so the finding is machine-parseable and the UI can render inline context at the exact location:\n\n```bash\nkspec review comment @review-ref --body \"Off-by-one error\" --kind blocker \\\n  --path path\u002Fto\u002Ffile.ext --side head --line-start 42 --line-end 42 \\\n  --commit def5678\n```\n\nFor multi-line ranges, set `--line-start` and `--line-end` to span the relevant block.\n\n#### Structured Anchors (for plans\u002Fspecs)\n\n**Always anchor plan and spec findings to specific sections and fields.** Use `--section`, `--field`, and `--anchor-ref` so the finding is tied to the exact AC, description field, or plan section — not just described in prose:\n\n```bash\nkspec review comment @review-ref --body \"AC is too vague\" --kind blocker \\\n  --section acceptance_criteria --field ac-3 --anchor-ref @spec-ref\n```\n\nCommon `--section` values: `acceptance_criteria`, `description`, `context`, `todos`. The `--field` identifies the specific item within that section (e.g., `ac-1`, `ac-2`). The `--anchor-ref` ties the anchor to a specific spec or plan item.\n\n#### Why Anchors Matter\n\nAnchored comments are machine-parseable and enable richer tooling: the UI can render findings inline at the exact location, agents can programmatically match findings to code or ACs, and fix-cycle workers can jump directly to the problem without re-reading the entire diff or spec.\n\n**Unanchored (avoid):**\n\n```bash\n# Finding describes location in body text — not machine-parseable\nkspec review comment @review-ref \\\n  --body \"In path\u002Fto\u002Ffile.ext around line 42, there's an off-by-one error\" \\\n  --kind blocker\n```\n\n**Anchored (preferred):**\n\n```bash\n# Finding anchored to exact file and lines — UI renders inline, agents can match\nkspec review comment @review-ref \\\n  --body \"Off-by-one error: loop should use \u003C instead of \u003C=\" --kind blocker \\\n  --path path\u002Fto\u002Ffile.ext --side head --line-start 42 --line-end 42 \\\n  --commit def5678\n```\n\n**Unanchored plan comment (avoid):**\n\n```bash\nkspec review comment @review-ref \\\n  --body \"The third acceptance criterion on @spec-auth is too vague\" \\\n  --kind blocker\n```\n\n**Anchored plan comment (preferred):**\n\n```bash\nkspec review comment @review-ref \\\n  --body \"AC is too vague — 'handles errors properly' needs specific error types\" \\\n  --kind blocker \\\n  --section acceptance_criteria --field ac-3 --anchor-ref @spec-auth\n```\n\n### Recording Checks\n\nChecks record verification evidence bound to the reviewed state. The `applies_to_version` is auto-derived from the review's subject — `code_compare` for code subjects, `entity_version` for task\u002Fplan\u002Fspec subjects — so callers do not provide version information.\n\nThe `--name` and `--runner` values are free-form labels — pick names that match the project's quality-gate vocabulary.\n\n```bash\n# Passing test run\nkspec review check @review-ref --name \"tests\" --status pass \\\n  --runner \u003Cproject-test-runner> --evidence \"All 342 tests passed\"\n\n# Failing check\nkspec review check @review-ref --name \"lint\" --status fail \\\n  --runner \u003Cproject-linter> --evidence \"3 errors found\"\n\n# Informational (non-required) check\nkspec review check @review-ref --name \"coverage\" --status pass \\\n  --no-required --evidence \"87% coverage\"\n```\n\n**Check statuses:** `pass`, `fail`, `running`, `skipped`\n\nChecks whose `applies_to_version` does not match the current subject version are stale.\n\n### Submitting Verdicts\n\nVerdicts record individual reviewer decisions. Like checks, the `applies_to_version` is auto-derived from the review's subject, so callers do not provide version information.\n\n```bash\n# Approve\nkspec review verdict @review-ref --decision approve \\\n  --reviewer agent@example.com\n\n# Request changes (triggers needs_work on linked task)\nkspec review verdict @review-ref --decision request_changes \\\n  --reviewer agent@example.com\n\n# Comment (non-blocking)\nkspec review verdict @review-ref --decision comment \\\n  --reviewer agent@example.com\n```\n\nVerdicts are per-reviewer. A later verdict from the same reviewer replaces the earlier one for the same version. Verdicts not matching the current subject version are stale.\n\n### Replying and Resolving Threads\n\n```bash\n# Reply to a thread\nkspec review reply @review-ref --thread \u003Cthread-ulid> \\\n  --body \"Fixed in commit abc1234\"\n\n# Resolve a thread\nkspec review resolve @review-ref --thread \u003Cthread-ulid>\n\n# Reopen if fix was insufficient\nkspec review reopen @review-ref --thread \u003Cthread-ulid>\n```\n\n### Fix Cycles (Re-review After Changes)\n\nWhen a task returns to `pending_review` after a fix cycle, the reviewer creates a **new** review record rather than updating the old one:\n\n```bash\n# The old review is already closed (auto-closed on verdict)\n# Create a fresh review for the new cycle\nkspec review add --title \"Review task-foo (cycle 2)\" \\\n  --subject-type task --subject-ref @task-foo\n\n# The task's review_ref now points to this new review\n# The prior review remains accessible via for-task\nkspec review for-task @task-foo  # Shows all reviews, current + historical\n```\n\nWhen reviewing a fix cycle, read the prior review's threads. If the worker resolved threads, verify their resolutions are correct — a resolved thread is a claim that the issue was fixed, not proof. Reopen threads where the fix is insufficient.\n\nIf dispatch workspace metadata is available, the new review's orientation will include a diff summary showing what changed since the prior review's examined commit.\n\n**Subject refresh** is still available for within-cycle updates (e.g., reviewer pushes a minor fix before verdicting):\n\n```bash\nkspec review refresh @review-ref --head new-commit-sha\n```\n\n### Task Integration\n\nReviews integrate with the task lifecycle:\n\n- Creating a task review auto-sets `task.review_ref` to the new review\n- A `request_changes` verdict auto-transitions `pending_review` tasks to `needs_work` and auto-closes the review\n- An `approve` verdict auto-closes the review\n- `kspec review for-task @ref` finds **all** linked reviews (current + historical)\n\n---\n\n## Finding Validation\n\nBefore emitting any finding, apply the **claim-disprove-emit** cycle:\n\n1. **State the claim.** What exactly is wrong? Be specific: file, line, behavior.\n2. **Try to disprove it.** Look for evidence the code is correct — guard clauses, tests covering the case, spec decisions justifying the approach.\n3. **If disproved, drop it.** Dropped candidates are the process working correctly.\n4. **If still valid, assess severity and confidence.**\n\n### Finding Quality\n\nEvery finding must include:\n\n- **Path and line** — exactly where the issue is\n- **Anchor** — use CLI anchor flags (`--path`\u002F`--line-start`\u002F`--line-end` for code, `--section`\u002F`--field`\u002F`--anchor-ref` for plans\u002Fspecs) so the finding is machine-parseable, not just described in body text\n- **Claim** — what is wrong, stated precisely\n- **Impact** — what breaks, what guarantee is lost\n- **Evidence** — what you observed that proves the claim\n\n### Severity Guide\n\n| Severity       | When to use                                                                               |\n| -------------- | ----------------------------------------------------------------------------------------- |\n| **MUST-FIX**   | Correctness, security, spec violation, coverage loss. High or medium confidence required. |\n| **SHOULD-FIX** | Likely correctness issue, missing boundary case, fragile code.                            |\n| **SUGGESTION** | Pure style, naming, formatting. Zero correctness implications.                            |\n\n**Default to MUST-FIX.** Only downgrade when you are certain the issue is cosmetic.\n\n---\n\n## Reviewer Workflow Summary\n\n1. **Discover context** — `kspec task get @ref`, `kspec item get @spec-ref`\n2. **Create review** — `kspec review add --subject-type task --subject-ref @ref` (creates a new record each cycle)\n3. **Open review** — `kspec review open @review-ref`\n4. **Investigate** — deterministic checks, then analytical checks\n5. **Record required checks** — `kspec review check` for each project-defined quality gate (format, lint, type, test, focused changed-file checks where the project defines them) plus the relevant `kspec validate` results. A clean approval needs passing evidence for every required gate named in your project's quality-gate guidance, or an explicit explanation for any skipped check.\n6. **Record ALL findings** — `kspec review comment` for each finding with appropriate kind. **Always use anchors:**\n   - Code reviews: `--path`, `--line-start`, `--line-end`, `--commit` to pin findings to exact source locations\n   - Plan\u002Fspec reviews: `--section`, `--field`, `--anchor-ref` to pin findings to specific ACs or fields\n7. **Verify completeness** — Before submitting a verdict, confirm you have searched all categories, recorded every finding, and verified each finding with evidence. A review with one blocker and an immediate verdict is almost always incomplete. Each fix cycle costs time — find everything in one pass. Equally, do not invent findings — every issue must be backed by evidence you ran or read, not just suspicion.\n8. **Submit verdict** — `kspec review verdict` (approve or request_changes — auto-closes the review)\n\n---\n\n## CLI Lookups\n\n| Need                             | Command                           |\n| -------------------------------- | --------------------------------- |\n| Spec + all ACs (own + inherited) | `kspec item get @spec-ref`        |\n| Trait definition + ACs           | `kspec item get @trait-slug`      |\n| Review details                   | `kspec review get @review-ref`    |\n| Reviews for a task               | `kspec review for-task @task-ref` |\n| All open reviews                 | `kspec review list --status open` |\n| Search by keyword                | `kspec search \"keyword\"`          |\n| All traits                       | `kspec trait list`                |\n| Validation                       | `kspec validate`                  |\n\n## Command Reference\n\n```bash\n# Create and query\nkspec review add [options]              # Create a review record\nkspec review get \u003Cref>                  # Show review details\nkspec review list [--status, --disposition, --subject-type, --reviewer, --task]\nkspec review for-task \u003Cref>             # Find reviews linked to a task\n\n# Comments and threads\nkspec review comment \u003Cref> [options]    # Add a comment thread\nkspec review reply \u003Cref> --thread \u003Culid> --body \"...\"\nkspec review resolve \u003Cref> --thread \u003Culid>\nkspec review reopen \u003Cref> --thread \u003Culid>\n\n# Checks and verdicts\nkspec review check \u003Cref> [options]      # Record a check result\nkspec review verdict \u003Cref> [options]    # Set a reviewer verdict\n\n# Lifecycle\nkspec review open \u003Cref>                 # draft → open\nkspec review close \u003Cref>                # → closed\nkspec review archive \u003Cref>              # → archived (permanent)\n\n# Subject management\nkspec review refresh \u003Cref> --head \u003Ccommit> [--base \u003Ccommit>]\n```\n\n## Integration\n\n- **`$kspec-merge`** — Merge gate checks review disposition before merging\n- **`$kspec-writing-specs`** — If review reveals spec gaps, update specs first\n- **`kspec validate`** — Automated validation complements manual review\n","\u003C!-- kspec-managed -->\n# Review\n\nHow to review work and use kspec review records. Covers creating reviews, structuring findings, AC coverage verification, and the full review record interface.\n\n## When to Use\n\n- Reviewing submitted work\n- Creating or managing review records\n- Verifying AC coverage\n\n## Review Principles\n\n### Adversarial Investigation\n\n**Worker claims are hypotheses, not facts.** When a commit message says \"all tests pass,\" verify it. When a note says \"fixed the type errors,\" check they're actually fixed and not suppressed. Workers are not lying — but they are biased toward believing their own work is correct. Your job is to independently verify.\n\n**Read the code before the description.** Start by reading the diff — what changed, what was added, what was removed. Form your own understanding. Only then read the task notes or PR description and compare. This prevents anchoring bias.\n\n**Treat justifications as claims to verify.** \"Pre-existing issue,\" \"out of scope,\" \"will be addressed in follow-up,\" \"this is the standard pattern\" — these require evidence, not acceptance.\n\n**A clean review is valid.** Not every submission has bugs. If you investigate thoroughly and find nothing wrong, approve. Do not invent findings to justify time spent. The goal is accuracy, not a finding quota.\n\n### Cognitive Biases to Counteract\n\n**Satisfaction of search** — After finding the first issue, your detection rate drops 25-50%. Finding one issue makes it MORE likely there are others. Deliberately increase scrutiny after your first finding.\n\n**Complexity bias** — Simple-looking changes (renames, test rewrites, config changes) receive less scrutiny because they \"look safe.\" These are where semantic bugs hide. Every submission gets the same investigation depth.\n\n**Anchoring** — Don't frame analysis around the author's stated intent. Assess what the code actually does, not what the author says it does.\n\n**Decision fatigue** — On the Nth review, reviewers default to approval. Every approval must be backed by specific evidence of verification.\n\n### Structured Exploration\n\nBefore rendering any verdict, complete both deterministic and analytical checks:\n\n**Deterministic checks** (run these, don't reason about them):\n\n```bash\nkspec item get @spec-ref                    # Own ACs + inherited trait ACs\nkspec validate --refs --warnings-ok         # Reference\u002Fschema sanity\nkspec validate --alignment --warnings-ok    # Spec\u002Ftask alignment baseline\nkspec validate --completeness --warnings-ok # AC coverage baseline\n\n# Run the project-defined quality gates (format \u002F lint \u002F type \u002F test, plus any\n# focused changed-file gates). The concrete commands are named in your\n# project's quality-gate guidance — do not assume a toolchain.\n\n# Confirm AC annotations exist for the spec and any inherited traits using\n# whatever search tool fits the project's test layout.\n```\n\nProject-defined gate failures are review blockers. Request changes rather than approving when these gates are red or missing without a documented reason. If repo-wide lint has a warning baseline, changed-file lint warnings are still review findings unless you verify they are pre-existing outside the submitted diff.\n\n**Analytical checks** (require reading and judgment):\n\n1. Read the diff — every changed file, not just the interesting ones\n2. Read surrounding context — unchanged files that interact with changed code\n3. Verify spec alignment — for each AC, confirm the code satisfies the behavior\n4. Verify at least one worker claim independently\n5. Search across categories — correctness, edge cases, error handling, security, test quality, integration\n\n**Complete ALL checks before recording any verdict.** Do not stop at the first finding. Each unrecorded finding becomes a future fix cycle that could have been avoided. Record every issue you find, then submit one verdict covering all of them.\n\n**Verify findings are real, not invented.** Every finding must be backed by evidence you can demonstrate — code you read, tests you ran, commands you executed. Run the test suite. If an AC implies edge case behavior (concurrency, boundary values, error paths), check whether tests actually cover those cases — missing edge case coverage is a must-fix. Do not emit findings based solely on reading code and reasoning about it; execute what you can to confirm.\n\n---\n\n## AC Coverage Verification\n\n### Own AC Coverage\n\nEvery acceptance criterion on the spec MUST have at least one annotated test.\n\n```bash\n# Get all ACs (own + inherited from traits)\nkspec item get @spec-ref\n\n# Search for annotations in test files using whatever search tool fits\n# the project's language and test layout.\n```\n\nAnnotations use language-appropriate comment syntax:\n\n```javascript\n\u002F\u002F AC: @spec-ref ac-1\nit('should validate input', () => { ... });\n```\n\n```python\n# AC: @spec-ref ac-1\ndef test_validates_input():\n    ...\n```\n\nBefore accepting coverage, confirm each annotation matches the AC text from `kspec item get` — not just the `ac-N` number. A test must actually prove the AC, not just touch the code path.\n\n### Trait AC Coverage\n\nWhen a spec implements traits, it inherits their ACs. Every inherited AC needs test coverage using the **trait's** ref:\n\n```javascript\n\u002F\u002F AC: @trait-json-output ac-1\nit('should output valid JSON with --json flag', () => { ... });\n```\n\n```bash\n# kspec validate reports uncovered trait ACs\nkspec validate\n```\n\nAny \"inherited trait AC(s) without test coverage\" warning is a blocker.\n\nIf a trait AC genuinely doesn't apply, annotate it with a reason:\n\n```javascript\n\u002F\u002F AC: @trait-json-output ac-3 — N\u002FA: this command has no tabular output\n```\n\nAnnotations must be standalone line comments, not embedded in block comments.\n\n### Source-Scanning Tests (Reject on Sight)\n\nAny test whose mechanism is reading implementation source files and asserting on their textual content is an automatic MUST-FIX — regardless of what AC it claims to cover, what language it's in, or how the file reading is accomplished. The technique is the problem, not the specific API used.\n\nThe test: \"does this source file contain this string?\" The answer tells you nothing about whether the feature works. These tests create the illusion of coverage while testing nothing, and they are the most common shortcut agents take when ACs are difficult to test behaviorally.\n\nWhen you encounter source-scanning tests, flag them as MUST-FIX with a request to replace with behavioral tests that exercise the system. If an AC genuinely cannot be tested by exercising behavior, that signals the AC needs revision — not that source scanning is acceptable.\n\n### Spec Alignment\n\nImplementation must match spec intent, not just pass tests:\n\n1. **Implementation exists** — Code handles the described behavior\n2. **Test exists** — A test validates the behavior\n3. **Behavior matches** — The test actually proves the AC, not just syntactically passes\n\n---\n\n## Review Records\n\nkspec stores first-party review records as durable artifacts in the shadow branch. They track the full lifecycle of reviewing work — threaded comments, check results, verdicts, and audit history.\n\n### Review Lifecycle\n\n```\ndraft → open → closed\n                 ↓\n              archived (terminal)\n```\n\n| State      | Meaning                                                           |\n| ---------- | ----------------------------------------------------------------- |\n| `draft`    | Review created but not yet started                                |\n| `open`     | Active review in progress                                         |\n| `closed`   | Review concluded (auto-closed on approve\u002Frequest_changes verdict) |\n| `archived` | Permanently archived                                              |\n\n**Auto-close on verdict:** When a reviewer submits an `approve` or `request_changes` verdict, the review record automatically transitions to `closed`. A `comment` verdict leaves the review open since it doesn't represent a final assessment. Each closed review is a point-in-time artifact.\n\n### Per-Cycle Review Model\n\nEach review cycle produces its own review record. Each review is a discrete artifact with its own verdict, and the collection of reviews across cycles comprises the full review history for the task.\n\n**How it works:**\n\n- When a task enters `pending_review`, the reviewer creates a **new** review record\n- If a prior closed review exists, it remains as a historical artifact\n- The task's `review_ref` is updated to point to the new record\n- Historical reviews are accessible via `kspec review for-task @ref` (returns all linked reviews)\n\n**Do NOT reopen old reviews.** Instead, create a fresh review for each cycle. This keeps each review's findings, verdict, and context self-contained.\n\n### Disposition (Computed)\n\nThe disposition is computed from verdicts, checks, and threads — not set directly:\n\n| Disposition         | Condition                                                                                                                                         |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pending`           | No verdicts, or only `comment` verdicts                                                                                                           |\n| `approved`          | At least one `approve` verdict matching current version, no blocking `request_changes`, all required gates passing, no unresolved blocker threads |\n| `changes_requested` | Any `request_changes` verdict matching current version, or required gates failing, or unresolved blocker threads                                  |\n\n### Creating Reviews\n\n```bash\n# Review a task (auto-links review_ref on the task)\nkspec review add --title \"Review task-add-auth\" \\\n  --subject-type task --subject-ref @task-add-auth\n\n# Review committed code (requires base\u002Fhead commits)\nkspec review add --title \"Review feature branch\" \\\n  --subject-type code --base abc1234 --head def5678 \\\n  --base-branch \u003Cproject-integration-branch> --head-branch \u003Cfeature-branch> \\\n  --related-ref @task-add-auth\n\n# Review a plan or spec\nkspec review add --title \"Review auth plan\" \\\n  --subject-type plan --subject-ref @plan-auth\n```\n\n**Subject types:** `task`, `code`, `plan`, `spec`, `external`\n\n### Structuring Findings as Threads\n\nEach finding becomes a thread with a kind that determines its impact:\n\n```bash\n# Blocker — must be resolved before approval\nkspec review comment @review-ref \\\n  --body \"Missing error handling for invalid input\" --kind blocker\n\n# Question — non-blocking, needs clarification\nkspec review comment @review-ref \\\n  --body \"Why was this approach chosen over X?\" --kind question\n\n# Nit — non-blocking, minor suggestion (default)\nkspec review comment @review-ref \\\n  --body \"Consider renaming this variable\" --kind nit\n```\n\n**Thread kinds:** `blocker` (blocks approval), `question` (non-blocking), `nit` (non-blocking, default).\n\nOnly blocker threads affect disposition. Unresolved nits and questions do not block approval.\n\n#### Code-Targeted Comments\n\n**Always anchor code findings to specific lines.** Use `--path`, `--line-start`, and `--line-end` so the finding is machine-parseable and the UI can render inline context at the exact location:\n\n```bash\nkspec review comment @review-ref --body \"Off-by-one error\" --kind blocker \\\n  --path path\u002Fto\u002Ffile.ext --side head --line-start 42 --line-end 42 \\\n  --commit def5678\n```\n\nFor multi-line ranges, set `--line-start` and `--line-end` to span the relevant block.\n\n#### Structured Anchors (for plans\u002Fspecs)\n\n**Always anchor plan and spec findings to specific sections and fields.** Use `--section`, `--field`, and `--anchor-ref` so the finding is tied to the exact AC, description field, or plan section — not just described in prose:\n\n```bash\nkspec review comment @review-ref --body \"AC is too vague\" --kind blocker \\\n  --section acceptance_criteria --field ac-3 --anchor-ref @spec-ref\n```\n\nCommon `--section` values: `acceptance_criteria`, `description`, `context`, `todos`. The `--field` identifies the specific item within that section (e.g., `ac-1`, `ac-2`). The `--anchor-ref` ties the anchor to a specific spec or plan item.\n\n#### Why Anchors Matter\n\nAnchored comments are machine-parseable and enable richer tooling: the UI can render findings inline at the exact location, agents can programmatically match findings to code or ACs, and fix-cycle workers can jump directly to the problem without re-reading the entire diff or spec.\n\n**Unanchored (avoid):**\n\n```bash\n# Finding describes location in body text — not machine-parseable\nkspec review comment @review-ref \\\n  --body \"In path\u002Fto\u002Ffile.ext around line 42, there's an off-by-one error\" \\\n  --kind blocker\n```\n\n**Anchored (preferred):**\n\n```bash\n# Finding anchored to exact file and lines — UI renders inline, agents can match\nkspec review comment @review-ref \\\n  --body \"Off-by-one error: loop should use \u003C instead of \u003C=\" --kind blocker \\\n  --path path\u002Fto\u002Ffile.ext --side head --line-start 42 --line-end 42 \\\n  --commit def5678\n```\n\n**Unanchored plan comment (avoid):**\n\n```bash\nkspec review comment @review-ref \\\n  --body \"The third acceptance criterion on @spec-auth is too vague\" \\\n  --kind blocker\n```\n\n**Anchored plan comment (preferred):**\n\n```bash\nkspec review comment @review-ref \\\n  --body \"AC is too vague — 'handles errors properly' needs specific error types\" \\\n  --kind blocker \\\n  --section acceptance_criteria --field ac-3 --anchor-ref @spec-auth\n```\n\n### Recording Checks\n\nChecks record verification evidence bound to the reviewed state. The `applies_to_version` is auto-derived from the review's subject — `code_compare` for code subjects, `entity_version` for task\u002Fplan\u002Fspec subjects — so callers do not provide version information.\n\nThe `--name` and `--runner` values are free-form labels — pick names that match the project's quality-gate vocabulary.\n\n```bash\n# Passing test run\nkspec review check @review-ref --name \"tests\" --status pass \\\n  --runner \u003Cproject-test-runner> --evidence \"All 342 tests passed\"\n\n# Failing check\nkspec review check @review-ref --name \"lint\" --status fail \\\n  --runner \u003Cproject-linter> --evidence \"3 errors found\"\n\n# Informational (non-required) check\nkspec review check @review-ref --name \"coverage\" --status pass \\\n  --no-required --evidence \"87% coverage\"\n```\n\n**Check statuses:** `pass`, `fail`, `running`, `skipped`\n\nChecks whose `applies_to_version` does not match the current subject version are stale.\n\n### Submitting Verdicts\n\nVerdicts record individual reviewer decisions. Like checks, the `applies_to_version` is auto-derived from the review's subject, so callers do not provide version information.\n\n```bash\n# Approve\nkspec review verdict @review-ref --decision approve \\\n  --reviewer agent@example.com\n\n# Request changes (triggers needs_work on linked task)\nkspec review verdict @review-ref --decision request_changes \\\n  --reviewer agent@example.com\n\n# Comment (non-blocking)\nkspec review verdict @review-ref --decision comment \\\n  --reviewer agent@example.com\n```\n\nVerdicts are per-reviewer. A later verdict from the same reviewer replaces the earlier one for the same version. Verdicts not matching the current subject version are stale.\n\n### Replying and Resolving Threads\n\n```bash\n# Reply to a thread\nkspec review reply @review-ref --thread \u003Cthread-ulid> \\\n  --body \"Fixed in commit abc1234\"\n\n# Resolve a thread\nkspec review resolve @review-ref --thread \u003Cthread-ulid>\n\n# Reopen if fix was insufficient\nkspec review reopen @review-ref --thread \u003Cthread-ulid>\n```\n\n### Fix Cycles (Re-review After Changes)\n\nWhen a task returns to `pending_review` after a fix cycle, the reviewer creates a **new** review record rather than updating the old one:\n\n```bash\n# The old review is already closed (auto-closed on verdict)\n# Create a fresh review for the new cycle\nkspec review add --title \"Review task-foo (cycle 2)\" \\\n  --subject-type task --subject-ref @task-foo\n\n# The task's review_ref now points to this new review\n# The prior review remains accessible via for-task\nkspec review for-task @task-foo  # Shows all reviews, current + historical\n```\n\nWhen reviewing a fix cycle, read the prior review's threads. If the worker resolved threads, verify their resolutions are correct — a resolved thread is a claim that the issue was fixed, not proof. Reopen threads where the fix is insufficient.\n\nIf dispatch workspace metadata is available, the new review's orientation will include a diff summary showing what changed since the prior review's examined commit.\n\n**Subject refresh** is still available for within-cycle updates (e.g., reviewer pushes a minor fix before verdicting):\n\n```bash\nkspec review refresh @review-ref --head new-commit-sha\n```\n\n### Task Integration\n\nReviews integrate with the task lifecycle:\n\n- Creating a task review auto-sets `task.review_ref` to the new review\n- A `request_changes` verdict auto-transitions `pending_review` tasks to `needs_work` and auto-closes the review\n- An `approve` verdict auto-closes the review\n- `kspec review for-task @ref` finds **all** linked reviews (current + historical)\n\n---\n\n## Finding Validation\n\nBefore emitting any finding, apply the **claim-disprove-emit** cycle:\n\n1. **State the claim.** What exactly is wrong? Be specific: file, line, behavior.\n2. **Try to disprove it.** Look for evidence the code is correct — guard clauses, tests covering the case, spec decisions justifying the approach.\n3. **If disproved, drop it.** Dropped candidates are the process working correctly.\n4. **If still valid, assess severity and confidence.**\n\n### Finding Quality\n\nEvery finding must include:\n\n- **Path and line** — exactly where the issue is\n- **Anchor** — use CLI anchor flags (`--path`\u002F`--line-start`\u002F`--line-end` for code, `--section`\u002F`--field`\u002F`--anchor-ref` for plans\u002Fspecs) so the finding is machine-parseable, not just described in body text\n- **Claim** — what is wrong, stated precisely\n- **Impact** — what breaks, what guarantee is lost\n- **Evidence** — what you observed that proves the claim\n\n### Severity Guide\n\n| Severity       | When to use                                                                               |\n| -------------- | ----------------------------------------------------------------------------------------- |\n| **MUST-FIX**   | Correctness, security, spec violation, coverage loss. High or medium confidence required. |\n| **SHOULD-FIX** | Likely correctness issue, missing boundary case, fragile code.                            |\n| **SUGGESTION** | Pure style, naming, formatting. Zero correctness implications.                            |\n\n**Default to MUST-FIX.** Only downgrade when you are certain the issue is cosmetic.\n\n---\n\n## Reviewer Workflow Summary\n\n1. **Discover context** — `kspec task get @ref`, `kspec item get @spec-ref`\n2. **Create review** — `kspec review add --subject-type task --subject-ref @ref` (creates a new record each cycle)\n3. **Open review** — `kspec review open @review-ref`\n4. **Investigate** — deterministic checks, then analytical checks\n5. **Record required checks** — `kspec review check` for each project-defined quality gate (format, lint, type, test, focused changed-file checks where the project defines them) plus the relevant `kspec validate` results. A clean approval needs passing evidence for every required gate named in your project's quality-gate guidance, or an explicit explanation for any skipped check.\n6. **Record ALL findings** — `kspec review comment` for each finding with appropriate kind. **Always use anchors:**\n   - Code reviews: `--path`, `--line-start`, `--line-end`, `--commit` to pin findings to exact source locations\n   - Plan\u002Fspec reviews: `--section`, `--field`, `--anchor-ref` to pin findings to specific ACs or fields\n7. **Verify completeness** — Before submitting a verdict, confirm you have searched all categories, recorded every finding, and verified each finding with evidence. A review with one blocker and an immediate verdict is almost always incomplete. Each fix cycle costs time — find everything in one pass. Equally, do not invent findings — every issue must be backed by evidence you ran or read, not just suspicion.\n8. **Submit verdict** — `kspec review verdict` (approve or request_changes — auto-closes the review)\n\n---\n\n## CLI Lookups\n\n| Need                             | Command                           |\n| -------------------------------- | --------------------------------- |\n| Spec + all ACs (own + inherited) | `kspec item get @spec-ref`        |\n| Trait definition + ACs           | `kspec item get @trait-slug`      |\n| Review details                   | `kspec review get @review-ref`    |\n| Reviews for a task               | `kspec review for-task @task-ref` |\n| All open reviews                 | `kspec review list --status open` |\n| Search by keyword                | `kspec search \"keyword\"`          |\n| All traits                       | `kspec trait list`                |\n| Validation                       | `kspec validate`                  |\n\n## Command Reference\n\n```bash\n# Create and query\nkspec review add [options]              # Create a review record\nkspec review get \u003Cref>                  # Show review details\nkspec review list [--status, --disposition, --subject-type, --reviewer, --task]\nkspec review for-task \u003Cref>             # Find reviews linked to a task\n\n# Comments and threads\nkspec review comment \u003Cref> [options]    # Add a comment thread\nkspec review reply \u003Cref> --thread \u003Culid> --body \"...\"\nkspec review resolve \u003Cref> --thread \u003Culid>\nkspec review reopen \u003Cref> --thread \u003Culid>\n\n# Checks and verdicts\nkspec review check \u003Cref> [options]      # Record a check result\nkspec review verdict \u003Cref> [options]    # Set a reviewer verdict\n\n# Lifecycle\nkspec review open \u003Cref>                 # draft → open\nkspec review close \u003Cref>                # → closed\nkspec review archive \u003Cref>              # → archived (permanent)\n\n# Subject management\nkspec review refresh \u003Cref> --head \u003Ccommit> [--base \u003Ccommit>]\n```\n\n## Integration\n\n- **`$kspec-merge`** — Merge gate checks review disposition before merging\n- **`$kspec-writing-specs`** — If review reveals spec gaps, update specs first\n- **`kspec validate`** — Automated validation complements manual review\n",{"name":5,"description":7},"main","c4b0de3035f8512bba7eb0a9b4e39ea2fbd3f08e",".agents\u002Fskills\u002Fkspec-review",2,"https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec","https:\u002F\u002Fgithub.com\u002Flepahc","2026-07-22 18:57:40",{"source":8,"skillName":5,"commands":40,"prompt":50,"zipAvailable":51},[41,44,47],{"tool":42,"command":43},"npx","npx skills add lepahc\u002Fkynetic-spec --skill kspec-review",{"tool":45,"command":46},"bunx","bunx skills add lepahc\u002Fkynetic-spec --skill kspec-review",{"tool":48,"command":49},"pnpm","pnpm dlx skills add lepahc\u002Fkynetic-spec --skill kspec-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkspec-review\u002FSKILL.md",true,[],[54,72,78,86,97,104],{"skillNo":55,"name":56,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":69,"publishedAt":27},"01M6C7KCZE43MDZ74FV3A5TDCQ","writing-specs","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Fwriting-specs\u002FSKILL.md",[59,64],{"categoryNo":60,"categoryName":61,"taxonomyType":62,"taxonomyTypeDesc":63},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":65,"categoryName":66,"taxonomyType":67,"taxonomyTypeDesc":68},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[70,71],"writing","writing specs",{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":27},"01M6C7KAK9CBJ87PX3BCW7B7YG","triage","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage\u002FSKILL.md",[],[74],{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":27},"01M6C7K89VN6FJCT8M86K56EE8","triage-inbox","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-inbox\u002FSKILL.md",[],[74,84,85],"inbox","triage inbox",{"skillNo":87,"name":88,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":94,"publishedAt":27},"01M6C7K6F2342AC1TJCN9PM0ZB","triage-automation","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-automation\u002FSKILL.md",[91],{"categoryNo":92,"categoryName":93,"taxonomyType":62,"taxonomyTypeDesc":63},"01JBSEEDCAT000000000000023","Skill与智能体开发",[74,95,96],"automation","triage automation",{"skillNo":98,"name":99,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":27},"01M6C7K3TFQ88QQBW3PXYDHQG2","task-work","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftask-work\u002FSKILL.md",[],[23,103],"task work",{"skillNo":105,"name":18,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":27},"01M6C7K168CH3XJCC3PDGA9H6C","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Freview\u002FSKILL.md",[],[18]]