diff --git a/.claude/skills/kiro-debug/SKILL.md b/.claude/skills/kiro-debug/SKILL.md new file mode 100644 index 00000000..ca88fe40 --- /dev/null +++ b/.claude/skills/kiro-debug/SKILL.md @@ -0,0 +1,152 @@ +--- +name: kiro-debug +description: Investigate implementation failures using root-cause-first debugging. Use when an implementer is blocked, verification fails, or repeated remediation does not converge. +allowed-tools: Read, Bash, Grep, Glob, WebSearch, WebFetch +argument-hint: +--- + +# kiro-debug + +## Overview + +This skill is for fresh-context root cause investigation. It combines local evidence, runtime/config inspection, and external documentation or issue research when available. It is not a patch generator for guess-first debugging. + +## When to Use + +- Implementer reports `BLOCKED` +- Reviewer rejection repeats after remediation +- Validation fails unexpectedly +- A task appears to conflict with runtime or platform reality +- The same failure survives more than one attempted fix + +Do not use this skill to speculate about fixes before gathering evidence. + +## Inputs + +Provide: +- Exact failure symptom or blocker statement +- Error messages, stack trace, and failing command output +- Current `git diff` or summary of uncommitted failed changes +- Task brief: what was being built +- Reviewer feedback, if the failure came from review rejection +- Relevant spec file paths (`requirements.md`, `design.md`) +- Relevant requirement/design section numbers +- Relevant `## Implementation Notes` +- Runtime or environment constraints already known + +## Outputs + +Return: +- `ROOT_CAUSE` +- `CATEGORY` +- `FIX_PLAN` +- `VERIFICATION` +- `NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN` +- `CONFIDENCE: HIGH | MEDIUM | LOW` +- `NOTES` + +Use the language specified in `spec.json`. + +## Method + +### 1. Read the Error Carefully +Extract: +- Exact error text +- Stack trace or failure location +- The command that produced the failure +- Whether the failure is deterministic or intermittent + +### 2. Inspect Local Runtime and Repository State +Inspect the repository for local evidence: +- `package.json`, `pyproject.toml`, `go.mod`, `Makefile`, `README*` +- Build config +- `tsconfig` or equivalent language/runtime config +- Runtime-specific config +- Dependency versions and scripts +- Relevant changed files from `git diff` + +### 3. Search the Web if Available +If web access is available, search: +- The exact error message +- The technology + symptom combination +- Official documentation +- Version-specific issue trackers or migration notes + +Prefer: +- Official docs +- Official repos/issues +- Version-specific references +- Runtime-specific documentation + +### 4. Classify the Root Cause +Use one category: +- `MISSING_DEPENDENCY` +- `RUNTIME_MISMATCH` +- `MODULE_FORMAT` +- `NATIVE_ABI` +- `CONFIG_GAP` +- `LOGIC_ERROR` +- `TASK_ORDERING_PROBLEM` +- `TASK_DECOMPOSITION_PROBLEM` +- `SPEC_CONFLICT` +- `EXTERNAL_DEPENDENCY` + +### 5. Determine the Smallest Safe Next Action +Decide whether the issue can be fixed inside this repo by: +- Editing files +- Adjusting configuration +- Adding or correcting dependencies +- Restructuring code + +Use `NEXT_ACTION: RETRY_TASK` when the issue is repo-fixable inside the current approved task plan. + +### 6. Determine Whether the Task Plan Is Still Valid +Decide whether the current approved task plan is still safe to execute as written. + +Prefer `NEXT_ACTION: STOP_FOR_HUMAN` when: +- A missing prerequisite task should exist before this one +- The current task is ordered incorrectly relative to unfinished work +- The current task boundary is wrong and should be split or merged +- The task is too large or ambiguous to fix safely inside the current implementation loop + +Use `NEXT_ACTION: BLOCK_TASK` only when the current task should stop but the rest of the queue can still proceed safely. + +Do not propose a brute-force code fix as a substitute for revising `tasks.md` or the approved plan. + +## Critical Rule + +Do not propose a multi-fix shotgun plan. Identify the root cause first, then produce the smallest plausible fix plan. If the true problem is a spec conflict or architecture problem, say so directly. + +## Stop / Escalate + +Use `NEXT_ACTION: STOP_FOR_HUMAN` when the blocker genuinely requires: +- Human product/requirements decision +- External credentials or inaccessible services +- Hardware or unavailable external systems +- Re-scoping due to spec/platform conflict + +If the issue is fixable by repo changes inside the current task plan, do not escalate prematurely. + +## Common Rationalizations + +| Rationalization | Reality | +|---|---| +| “This probably just needs a quick patch” | Patch-first debugging creates rework. | +| “Let’s try a few fixes” | Multi-fix guessing hides root cause. | +| “The spec is probably wrong, I’ll adapt it” | Spec conflicts must be surfaced explicitly. | +| “The docs search is optional” | For runtime/dependency issues, docs and version issues often contain the shortest path to root cause. | + +## Output Format + +```md +## Debug Report +- ROOT_CAUSE: <1-2 sentence root cause> +- CATEGORY: MISSING_DEPENDENCY | RUNTIME_MISMATCH | MODULE_FORMAT | NATIVE_ABI | CONFIG_GAP | LOGIC_ERROR | TASK_ORDERING_PROBLEM | TASK_DECOMPOSITION_PROBLEM | SPEC_CONFLICT | EXTERNAL_DEPENDENCY +- FIX_PLAN: + 1. + 2. +- VERIFICATION: +- NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN +- CONFIDENCE: HIGH | MEDIUM | LOW +- NOTES: +``` diff --git a/.claude/skills/kiro-discovery/SKILL.md b/.claude/skills/kiro-discovery/SKILL.md new file mode 100644 index 00000000..d6c89d5d --- /dev/null +++ b/.claude/skills/kiro-discovery/SKILL.md @@ -0,0 +1,262 @@ +--- +name: kiro-discovery +description: Entry point for new work. Determines the best action path or work decomposition (update existing spec, create new spec, mixed decomposition, or no spec needed) and refines ideas through structured dialogue. +disable-model-invocation: true +allowed-tools: Read, Write, Glob, Grep, Agent, WebSearch, WebFetch, AskUserQuestion +argument-hint: +--- + +# kiro-discovery Skill + +## Core Mission +- **Success Criteria**: + - Correct action path or work decomposition identified based on existing project state + - User's intent clarified through questions, not assumptions + - Output is an actionable next step (not just a description) + +## Execution Steps + +### Step 1: Lightweight Scan + +Gather **only metadata** to determine the action path. Do NOT read full file contents yet. + +- **Specs inventory**: Glob `.kiro/specs/*/spec.json`, read each spec.json for `name`, `phase` fields and `approvals` status. Note feature names and their current status. +- **Steering existence**: Check which files exist in `.kiro/steering/` (product.md, tech.md, structure.md, roadmap.md). Do NOT read their contents yet. +- **Roadmap check**: If `.kiro/steering/roadmap.md` exists, read it. This contains project-level context (approach, scope, constraints, spec list) from a previous discovery session. Use it to restore project context. +- **Top-level structure**: List the project root directory to note key directories and files. Do NOT recurse into subdirectories. + +This step should consume minimal context. If `specs/` is empty and no steering exists, note "greenfield project" and move to Step 2. + +### Step 2: Determine Action Path + +Based on the user's request and the metadata from Step 1, determine which path applies: + +**Path A: Existing spec covers this** +- The request is an extension, enhancement, or fix within an existing spec's domain +- Every meaningful part of the request fits that same spec boundary +- Any remaining small follow-up work can be handled directly without creating a new spec +- Skip remaining steps + +**Path B: No spec needed** +- The request is a bug fix, config change, simple refactor, or trivial addition +- No meaningful part of the request needs a new or updated spec boundary +- The request does not need to update an existing spec either +- Skip remaining steps + +**Path C: New single-scope feature** +- The request is new, doesn't overlap with existing specs, and fits in one spec + +**Path D: Multi-scope decomposition needed** +- The request spans multiple domains or would produce 20+ tasks in a single spec + +**Path E: Mixed decomposition** +- The request contains a mix of: existing spec extensions, one or more new spec candidates, and optional direct-implementation work +- Use this path only when at least one genuinely new spec boundary is needed + +For Path C/D/E, present the determined path (or mixed decomposition) to the user and confirm before proceeding. +For Path A/B, recommend the next action and stop. + +### Step 3: Deep Context Loading + +**Only for Path C, D, and E.** Now load the context needed for discovery. + +**In main context** (essential for dialogue with user): +- **Steering documents**: Read product.md and tech.md (if they exist) for project goals, constraints, and tech stack +- **Relevant specs**: If the request is adjacent to an existing spec, read that spec's requirements.md to understand boundaries and avoid overlap + +**Delegate to subagent via Agent tool** (keeps exploration out of main context): +- **Codebase exploration**: Dispatch a subagent to explore the codebase and return a structured summary. Example prompt: "Explore this project's codebase. Summarize: (1) tech stack and frameworks, (2) directory structure and key modules, (3) patterns and conventions used, (4) areas relevant to [user's request]. Return a summary under 200 lines." +- The subagent uses Read/Glob/Grep to explore, then returns findings. Only the summary enters the main context. +- For Path D/E, also ask the subagent to identify natural domain boundaries, existing module separation, and which areas look like existing-spec extensions vs new boundaries. +- Skip subagent dispatch for small/obvious requests where the top-level directory listing from Step 1 is sufficient. + +**Context budget**: Keep total content loaded into main context under ~500 lines. The subagent handles the heavy exploration. + +### Step 4: Understand the Idea + +Ask clarifying questions **sequentially** (not all at once), prioritizing boundary discovery over feature detail: + +1. **Who and why**: Who has the problem? What pain does it cause? +2. **Desired outcome**: What should be true when this is done? +3. **Boundary candidates**: What are the natural responsibility seams in this work? Where could this be split so implementation can proceed independently? +4. **Out of boundary**: What should this spec explicitly NOT own, even if related? +5. **Existing vs new**: Which parts seem like extensions to existing specs, and which parts look like genuinely new boundaries? +6. **Upstream / downstream**: What existing systems, specs, or components does this depend on? What future work is likely to depend on this? +7. **Constraints**: Are there technology, timeline, or compatibility constraints? + +Ask only questions whose answers you cannot infer from the context already loaded. Skip questions that steering documents already answer. If the user already provided a clear description, skip to Step 5. +The goal is NOT to assign final owners yet. The goal is to discover the cleanest responsibility boundaries that can later become specs, tasks, and review scopes. + +### Step 5: Propose Approaches + +Propose **2-3 concrete approaches** with trade-offs: + +For each approach: +- **Approach name**: One-line summary +- **How it works**: 2-3 sentences on the technical approach +- **Pros**: What makes this approach good +- **Cons**: What are the risks or downsides +- **Scope estimate**: Rough complexity (small / medium / large) + +If technical research is needed (unfamiliar framework, library evaluation), dispatch a subagent via Agent tool. Example prompt: "Research [topic]: compare options, check latest versions, note known issues. Return a summary of findings with recommendation." The subagent uses WebSearch/WebFetch and returns a concise summary. Raw search results never enter the main context. + +Recommend one approach and explain why. + +**After the user selects an approach**, dispatch a subagent to verify viability before proceeding to Step 6. Example prompt: "Verify the viability of this technical approach: [chosen tech stack / key libraries]. Check: (1) Are these technologies still actively maintained? (2) Any license incompatibilities (e.g., GPL contamination)? (3) Do the components actually work together for [use case]? (4) Any known showstoppers (critical bugs, security vulnerabilities, platform limitations)? Return only issues found, or 'No issues found' if everything checks out." + +If the viability check reveals issues, present them to the user and revisit the approach selection. If no issues, proceed to Step 6. + +### Step 6: Refine and Confirm + +- Address user's questions or concerns about the approaches +- Narrow scope if needed: favor smaller, deliverable increments and cleaner responsibility seams +- For Path D/E: propose work decomposition with dependency ordering + - Each new boundary-worthy feature = one spec + - Existing spec extensions are explicitly listed with their target spec + - Truly small direct-implementation items are listed separately instead of being forced into a spec + - Dependencies between specs/workstreams are explicit + - Consider vertical slices (end-to-end value) vs horizontal layers (one layer at a time) based on the project needs +- Confirm the final direction + +### Step 7: Write Files to Disk + +**CRITICAL: You MUST use the Write tool to create these files BEFORE suggesting any next command. Conversation text does not survive session boundaries. If you skip this step, all discovery analysis is lost when the session ends.** + +**For Path C (single spec)**: + +Use the Write tool to create `.kiro/specs//brief.md` with this structure: + +``` +# Brief: + +## Problem +[who has the problem, what pain it causes] + +## Current State +[what exists today, what's the gap] + +## Desired Outcome +[what should be true when done] + +## Approach +[chosen approach and why] + +## Scope +- **In**: [what this feature includes] +- **Out**: [what's explicitly excluded] + +## Boundary Candidates +- [responsibility seam 1] +- [responsibility seam 2] + +## Out of Boundary +- [explicit non-goals this spec does not own] + +## Upstream / Downstream +- **Upstream**: [existing systems/specs this depends on] +- **Downstream**: [likely consumers or follow-on specs] + +## Existing Spec Touchpoints +- **Extends**: [existing spec(s) this work updates, if any] +- **Adjacent**: [neighbor specs or modules to avoid overlapping] + +## Constraints +[technology, compatibility, or other constraints] +``` + +**For Path D (multi-spec decomposition)**: + +Use the Write tool to create: +- `.kiro/steering/roadmap.md` +- `.kiro/specs//brief.md` for every feature listed under `## Specs (dependency order)` + +Use this roadmap structure: + +``` +# Roadmap + +## Overview +[Project goal and chosen approach -- 1-2 paragraphs] + +## Approach Decision +- **Chosen**: [approach name and summary] +- **Why**: [key reasoning] +- **Rejected alternatives**: [what was considered and why it was rejected] + +## Scope +- **In**: [what the overall project includes] +- **Out**: [what is explicitly excluded] + +## Constraints +[technology, compatibility, timeline, or other project-wide constraints] + +## Boundary Strategy +- **Why this split**: [why these spec boundaries improve independence] +- **Shared seams to watch**: [cross-spec boundaries needing careful review] + +## Specs (dependency order) +- [ ] feature-a -- [one-line description]. Dependencies: none +- [ ] feature-b -- [one-line description]. Dependencies: feature-a +- [ ] feature-c -- [one-line description]. Dependencies: feature-a, feature-b +``` + +Then create `.kiro/specs//brief.md` for **every** feature listed under `## Specs (dependency order)` using the Path C brief format. This enables parallel spec creation via `/kiro-spec-batch`. + +**For Path E (mixed decomposition)**: + +Use the same roadmap structure as Path D, plus these additional sections: + +``` +## Existing Spec Updates +- [ ] existing-feature-a -- [one-line description of the extension]. Dependencies: none +- [ ] existing-feature-b -- [one-line description of the extension]. Dependencies: feature-a + +## Direct Implementation Candidates +- [ ] small-item-a -- [why this stays direct implementation] +- [ ] small-item-b -- [why this stays direct implementation] + +## Specs (dependency order) +- [ ] new-feature-a -- [one-line description]. Dependencies: none +- [ ] new-feature-b -- [one-line description]. Dependencies: new-feature-a +``` + +Path E rules: +- Keep `## Specs (dependency order)` reserved for **new specs only** so `/kiro-spec-batch` can still parse it unchanged +- Record existing-spec extensions under `## Existing Spec Updates` +- Record true no-spec work under `## Direct Implementation Candidates` +- Create `brief.md` only for the **new specs** listed under `## Specs (dependency order)` + +**Re-entry (roadmap.md already exists)**: +Use the Write tool to create the next new spec's brief.md. Update roadmap.md with Write tool if scope/ordering changed, preserving completed items and prior phases. + +After writing, verify the files exist by reading them back. + +### Step 8: Suggest Next Steps + +Suggest the next command and stop. Do NOT automatically run downstream spec generation from this skill. + +- Path A: `/kiro-spec-requirements {feature}` to update the existing spec +- Path B: Recommend direct implementation without creating a spec +- Path C: Default to `/kiro-spec-init ` + - Optional fast path: `/kiro-spec-quick ` when the user explicitly wants to continue immediately +- Path D: Default to `/kiro-spec-batch` (creates all specs in parallel based on roadmap.md dependency order) + - Optional cautious path: `/kiro-spec-init ` when the user wants to validate the first slice before batching the rest +- Path E: Choose the next command based on the new-spec portion of the decomposition + - If there is exactly one new spec: `/kiro-spec-init ` + - If there are multiple new specs: `/kiro-spec-batch` + - Also note which existing specs should be revisited with `/kiro-spec-requirements ` +- Re-entry: `/kiro-spec-init ` or `/kiro-spec-batch` if multiple specs remain + +If the decomposition contains only existing-spec updates plus direct implementation candidates, do NOT use Path E. Prefer Path A when one existing spec is the clear home, or recommend the existing-spec update plus direct implementation work without creating roadmap entries. + +## Critical Constraints +- **Files on disk are the source of continuity**: For Path C/D/E, create brief.md and roadmap.md as needed before suggesting the next command. Do NOT leave discovery results only in conversation text. + +## Safety & Fallback + +**Roadmap Already Exists (re-entry)**: +- Read roadmap.md to restore project context before asking questions +- Determine next spec based on completed specs' status +- Write brief.md for the next spec only (just-in-time) +- Update roadmap.md if scope/ordering changed based on implementation experience +- Append new specs as a new phase if the request expands the project, don't overwrite existing content diff --git a/.claude/skills/kiro-impl/SKILL.md b/.claude/skills/kiro-impl/SKILL.md new file mode 100644 index 00000000..a64520bb --- /dev/null +++ b/.claude/skills/kiro-impl/SKILL.md @@ -0,0 +1,246 @@ +--- +name: kiro-impl +description: Implement approved tasks using TDD with native subagent dispatch. Runs all pending tasks autonomously or selected tasks manually. +disable-model-invocation: true +allowed-tools: Read, Write, Edit, MultiEdit, Bash, Glob, Grep, Agent, WebSearch, WebFetch +argument-hint: [task-numbers] +--- + +# kiro-impl Skill + +## Role +You operate in two modes: +- **Autonomous mode** (no task numbers): Dispatch a fresh subagent per task, with independent review after each +- **Manual mode** (task numbers provided): Execute selected tasks directly in the main context + +## Core Mission +- **Success Criteria**: + - All tests written before implementation code + - Code passes all tests with no regressions + - Tasks marked as completed in tasks.md + - Implementation aligns with design and requirements + - Independent reviewer approves each task before completion + +## Execution Steps + +### Step 1: Gather Context + +If steering/spec context is already available from conversation, skip redundant file reads. +Otherwise, load all necessary context: +- `.kiro/specs/{feature}/spec.json`, `requirements.md`, `design.md`, `tasks.md` +- Core steering context: `product.md`, `tech.md`, `structure.md` +- Additional steering files only when directly relevant to the selected task's boundary, runtime prerequisites, integrations, domain rules, security/performance constraints, or team conventions that affect implementation or validation +- Relevant local agent skills or playbooks only when they clearly match the task's host environment or use case; read the specific artifact(s) you need, not entire directories + +#### Parallel Research + +The following research areas are independent and can be executed in parallel: +1. **Spec context loading**: spec.json, requirements.md, design.md, tasks.md +2. **Steering, playbooks, & patterns**: Core steering, task-relevant extra steering, matching local agent skills/playbooks, and existing code patterns + +After all parallel research completes, synthesize implementation brief before starting. + +#### Preflight + +**Validate approvals**: +- Verify tasks are approved in spec.json (stop if not, see Safety & Fallback) + +**Discover validation commands**: +- Inspect repository-local sources of truth in this order: project scripts/manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, app manifests), task runners (`Makefile`, `justfile`), CI/workflow files, existing e2e/integration configs, then `README*` +- Derive a canonical validation set for this repo: `TEST_COMMANDS`, `BUILD_COMMANDS`, and `SMOKE_COMMANDS` +- Prefer commands already used by repo automation over ad hoc shell pipelines +- For `SMOKE_COMMANDS`, choose the lightest trustworthy runtime-liveness check for the app shape (for example: root URL load, Electron launch, CLI `--help`, service health endpoint, mobile simulator/e2e harness if one already exists) +- Keep the full command set in the parent context, and pass only the task-relevant subset to implementer and reviewer subagents + +**Establish repo baseline**: +- Run `git status --porcelain` and note any pre-existing uncommitted changes + +### Step 2: Select Tasks & Determine Mode + +**Parse arguments**: +- Extract feature name from first argument +- If task numbers provided (e.g., "1.1" or "1,2,3"): **manual mode** +- If no task numbers: **autonomous mode** (all pending tasks) + +**Build task queue**: +- Read tasks.md, identify actionable sub-tasks (X.Y numbering like 1.1, 2.3) +- Major tasks (1., 2.) are grouping headers, not execution units +- Skip tasks with `_Blocked:_` annotation +- For each selected task, check `_Depends:_` annotations -- verify referenced tasks are `[x]` +- If prerequisites incomplete, execute them first or warn the user +- Use `_Boundary:_` annotations to understand the task's component scope + +### Step 3: Execute Implementation + +#### Autonomous Mode (subagent dispatch) + +**Iteration discipline**: Process exactly ONE sub-task (e.g., 1.1) per iteration. Do NOT batch multiple sub-tasks into a single subagent dispatch. Each iteration follows the full cycle: dispatch implementer → review → commit → re-read tasks.md → next. + +**Context management**: At the start of each iteration, re-read `tasks.md` to determine the next actionable sub-task. Do NOT rely on accumulated memory of previous iterations. After completing each iteration, retain only a one-line summary (e.g., "1.1: READY_FOR_REVIEW, 3 files changed") and discard the full status report and reviewer details. + +For each task (one at a time): + +**a) Dispatch implementer**: +- Read `templates/implementer-prompt.md` from this skill's directory +- Construct a prompt by combining the template with task-specific context: + - Task description and boundary scope + - Paths to spec files: requirements.md, design.md, tasks.md + - Exact requirement and design section numbers this task must satisfy (using source numbering, NOT invented `REQ-*` aliases) + - Task-relevant steering context and parent-discovered validation commands (tests/build/smoke as relevant) + - Whether the task is behavioral (Feature Flag Protocol) or non-behavioral + - **Previous learnings**: Include any `## Implementation Notes` entries from tasks.md that are relevant to this task's boundary or dependencies (e.g., "better-sqlite3 requires separate rebuild for Electron"). This prevents the same mistakes from recurring. +- The implementer subagent will read the spec files and build its own Task Brief (acceptance criteria, completion definition, design constraints, verification method) before implementation +- Dispatch via **Agent tool** as a fresh subagent + +**b) Handle implementer status**: +- Parse implementer status only from the exact `## Status Report` block and `- STATUS:` field. +- If `STATUS` is missing, ambiguous, or replaced with prose, re-dispatch the implementer once requesting the exact structured status block only. Do NOT proceed to review without a parseable `READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT` value. +- **READY_FOR_REVIEW** → proceed to review +- **BLOCKED** → dispatch debug subagent (see section below); do NOT immediately skip +- **NEEDS_CONTEXT** → re-dispatch once with the requested additional context; if still unresolved → dispatch debug subagent + +**c) Dispatch reviewer**: +- Read `templates/reviewer-prompt.md` from this skill's directory +- Construct a review prompt with: + - The task description and relevant spec section numbers + - Paths to spec files (requirements.md, design.md) so the reviewer can read them directly + - The implementer's status report (for reference only — reviewer must verify independently) +- The reviewer must apply the `kiro-review` protocol to this task-local review. +- Preserve the existing task-specific context: task text, spec refs, `_Boundary:_` scope, validation commands, implementer report, and the actual `git diff` as the primary source of truth. +- The reviewer subagent will run `git diff` itself to read the actual code changes and verify against the spec +- Dispatch via **Agent tool** as a fresh subagent + +**d) Handle reviewer verdict**: +- Parse reviewer verdict only from the exact `## Review Verdict` block and `- VERDICT:` field. +- If `VERDICT` is missing, ambiguous, or replaced with prose, re-dispatch the reviewer once requesting the exact structured verdict only. Do NOT mark the task complete, commit, or continue to the next task without a parseable `APPROVED | REJECTED` value. +- **APPROVED** → before marking the task `[x]` or making any success claim, apply `kiro-verify-completion` using fresh evidence from the current code state; then mark task `[x]` in tasks.md and perform selective git commit +- **REJECTED (round 1-2)** → re-dispatch implementer with review feedback +- **REJECTED (round 3)** → dispatch debug subagent (see section below) + +**e) Commit** (parent-only, selective staging): +- Stage only the files actually changed for this task, plus tasks.md +- **NEVER** use `git add -A` or `git add .` +- Use `git add ...` with explicit file paths +- Commit message format: `feat(): ` + +**f) Record learnings**: +- If this task revealed cross-cutting insights, append a one-line note to the `## Implementation Notes` section at the bottom of tasks.md + +**g) Debug subagent** (triggered by BLOCKED, NEEDS_CONTEXT unresolved, or REJECTED after 2 remediation rounds): + +The debug subagent runs in a **fresh context** — it receives only the error information, not the failed implementation history. This avoids the context pollution that causes infinite retry loops. + +- Read `templates/debugger-prompt.md` from this skill's directory +- Construct a debug prompt with: + - The error description / blocker reason / reviewer rejection findings + - `git diff` of the current uncommitted changes + - The task description and relevant spec section numbers + - Paths to spec files so the debugger can read them +- The debugger must apply the `kiro-debug` protocol to this failure investigation. +- Preserve rich failure context: error output, reviewer findings, current `git diff`, task/spec refs, and any relevant Implementation Notes. +- When available, the debugger should inspect runtime/config state and use web or official documentation research to validate root-cause hypotheses before proposing a fix plan. +- Dispatch via **Agent tool** as a fresh subagent + +**Handle debug report**: +- Parse `NEXT_ACTION` from the debug report's exact structured field. +- If `NEXT_ACTION: STOP_FOR_HUMAN` → append `_Blocked: _` to tasks.md, stop the feature run, and report that human review is required before continuing +- If `NEXT_ACTION: BLOCK_TASK` → append `_Blocked: _` to tasks.md, skip to next task +- If `NEXT_ACTION: RETRY_TASK` → preserve the current worktree; do NOT reset or discard unrelated changes. Spawn a **new** implementer subagent with the debug report's `FIX_PLAN`, `NOTES`, and the current `git diff`, and require it to repair the task with explicit edits only + - If the new implementer succeeds (READY_FOR_REVIEW → reviewer APPROVED) → normal flow + - If the new implementer also fails → repeat debug cycle (max 2 debug rounds total). After 2 failed debug rounds → append `_Blocked: debug attempted twice, still failing — _` to tasks.md, skip +- **Max 2 debug rounds per task**. Each round: fresh debug subagent → fresh implementer. If still failing after 2 rounds, the task is blocked. +- Record debug findings in `## Implementation Notes` (this helps subsequent tasks avoid the same issue) + +**`(P)` markers**: Tasks marked `(P)` in tasks.md indicate they have no inter-dependencies and could theoretically run in parallel. However, kiro-impl processes them sequentially (one at a time) to avoid git conflicts and simplify review. The `(P)` marker is informational for task planning, not an execution directive. + +**Completion check**: If all remaining tasks are BLOCKED, stop and report blocked tasks with reasons to the user. + +#### Manual Mode (main context) + +For each selected task: + +**1. Build Task Brief**: +Before writing any code, read the relevant sections of requirements.md and design.md for this task and clarify: +- What observable behaviors must be true when done (acceptance criteria) +- What files/functions/tests must exist (completion definition) +- What technical decisions to follow from design.md (design constraints) +- How to confirm the task works (verification method) + +**2. Execute TDD cycle** (Kent Beck's RED → GREEN → REFACTOR): +- **RED**: Write test for the next small piece of functionality based on the acceptance criteria. Test should fail. +- **GREEN**: Implement simplest solution to make test pass, following the design constraints. +- **REFACTOR**: Improve code structure, remove duplication. All tests must still pass. +- **VERIFY**: All tests pass (new and existing), no regressions. Confirm verification method passes. +- **REVIEW**: Apply `kiro-review` before marking the task complete. If the host supports fresh subagents in manual mode, use a fresh reviewer; otherwise perform the review in the main context using the `kiro-review` protocol. Do NOT continue until the verdict is parseably `APPROVED`. +- **MARK COMPLETE**: Only after review returns `APPROVED`, apply `kiro-verify-completion`, then update the checkbox from `- [ ]` to `- [x]` in tasks.md. + +### Step 4: Final Validation + +**Autonomous mode**: +- After all tasks complete, run `/kiro-validate-impl {feature}` as a GO/NO-GO gate +- If validation returns GO → before reporting feature success, apply `kiro-verify-completion` to the feature-level claim using the validation result and fresh supporting evidence +- If validation returns NO-GO: + - Fix only concrete findings from the validation report + - Cap remediation at 3 rounds; if still NO-GO, stop and report remaining findings +- If validation returns MANUAL_VERIFY_REQUIRED → stop and report the missing verification step + +**Manual mode**: +- Suggest running `/kiro-validate-impl {feature}` but do not auto-execute + +## Feature Flag Protocol + +For tasks that add or change behavior, enforce RED → GREEN with a feature flag: + +1. **Add flag** (OFF by default): Introduce a toggle appropriate to the codebase (env var, config constant, boolean, conditional -- agent chooses the mechanism) +2. **RED -- flag OFF**: Write tests for the new behavior. Run tests → must FAIL. If tests pass with flag OFF, the tests are not testing the right thing. Rewrite. +3. **GREEN -- flag ON + implement**: Enable the flag, write implementation. Run tests → must PASS. +4. **Remove flag**: Make the code unconditional. Run tests → must still PASS. + +**Skip this protocol for**: refactoring, configuration, documentation, or tasks with no behavioral change. + +## Critical Constraints +- **Strict Handoff Parsing**: Never infer implementer `STATUS` or reviewer `VERDICT` from surrounding prose; only the exact structured fields count +- **No Destructive Reset**: Never use `git checkout .`, `git reset --hard`, or similar destructive rollback inside the implementation loop +- **Selective Staging**: NEVER use `git add -A` or `git add .`; always stage explicit file paths +- **Bounded Review Rounds**: Max 2 implementer re-dispatch rounds per reviewer rejection, then debug +- **Bounded Debug**: Max 2 debug rounds per task (debug + re-implementation per round); if still failing → BLOCKED +- **Bounded Remediation**: Cap final-validation remediation at 3 rounds + +## Output Description + +**Autonomous mode**: For each task, report: +1. Task ID, implementer status, reviewer verdict +2. Files changed, commit hash +3. After all tasks: final validation result (GO/NO-GO) + +**Manual mode**: +1. Tasks executed: task numbers and test results +2. Status: completed tasks marked in tasks.md, remaining tasks count + +**Format**: Concise, in the language specified in spec.json. + +## Safety & Fallback + +### Error Scenarios + +**Tasks Not Approved or Missing Spec Files**: +- **Stop Execution**: All spec files must exist and tasks must be approved +- **Suggested Action**: "Complete previous phases: `/kiro-spec-requirements`, `/kiro-spec-design`, `/kiro-spec-tasks`" + +**Test Failures**: +- **Stop Implementation**: Fix failing tests before continuing +- **Action**: Debug and fix, then re-run + +**All Tasks Blocked**: +- Stop and report all blocked tasks with reasons +- Human review needed to resolve blockers + +**Spec Conflicts with Reality**: +- If a requirement or design conflicts with reality (API doesn't exist, platform limitation), block the task with `_Blocked: _` -- do not silently work around it + +**Upstream Ownership Detected**: +- If review, debug, or validation shows that the root cause belongs to an upstream, foundation, shared-platform, or dependency spec, do not patch around it inside the downstream feature +- Route the fix back to the owning upstream spec, keep the downstream task blocked until that contract is repaired, and re-run validation/smoke for dependent specs after the upstream fix lands + +**Task Plan Invalidated During Implementation**: +- If debug returns `NEXT_ACTION: STOP_FOR_HUMAN` because of task ordering, boundary, or decomposition problems, stop and return for human review of `tasks.md` or the approved plan instead of forcing a code workaround diff --git a/.claude/skills/kiro-impl/templates/debugger-prompt.md b/.claude/skills/kiro-impl/templates/debugger-prompt.md new file mode 100644 index 00000000..ee958bf8 --- /dev/null +++ b/.claude/skills/kiro-impl/templates/debugger-prompt.md @@ -0,0 +1,54 @@ +# Debug Investigator + +Apply the `kiro-debug` protocol for this fresh-context root-cause investigation. + +If the host can invoke skills directly inside subagents, use `kiro-debug` as the governing debug protocol. Otherwise, follow the full investigation procedure embedded in this prompt, including local runtime inspection and web or official docs research when available. + +You are a fresh debug investigator with NO prior context about implementation attempts. Your sole job is root cause analysis and producing a concrete fix plan. + +## You Will Receive +- Error description and messages +- `git diff` of the failed changes (or a summary) +- Task brief (what was being built) +- Reviewer feedback (if the failure came from review rejection) +- Relevant spec file paths (requirements.md, design.md) + +## Method + +1. **Read the error carefully** — extract the exact error message, stack trace, and failure location +2. **Search the web** if available — search the exact error message, the technology + symptom combination, and official documentation + - e.g., `site:electronjs.org "Cannot find module"`, `better-sqlite3 electron ABI mismatch` + - Check GitHub Issues for the specific package/framework version +3. **Inspect the runtime environment** — check package.json (dependencies, scripts, main/module fields), build config, tsconfig, and any runtime-specific configuration +4. **Classify the root cause**: + - **Missing dependency**: A required package is not installed or not configured + - **Runtime mismatch**: Code works in one runtime (e.g., Node.js) but not the target (e.g., Electron, browser, Lambda) + - **Module format conflict**: ESM vs CJS incompatibility + - **Native module ABI**: Binary compiled for wrong runtime/version + - **Configuration gap**: Missing entry point, build output format, or runtime flags + - **Logic error**: Actual bug in the implementation + - **Spec conflict**: Requirements or design contradicts what's technically possible + - **External dependency**: Requires human decision, external API access, or hardware +5. **Determine if repo-fixable** — can this be resolved by editing files, adding dependencies, or changing configuration within this repository? + +## Critical Rule + +Do not collapse this investigation into guess-first patching; preserve category classification, repo-fixability judgment, and explicit verification commands. + +Use `NEXT_ACTION: STOP_FOR_HUMAN` only when the fix genuinely requires something outside the repository or the approved task plan is no longer safe to continue. If the fix is adding a dependency, changing a config file, or restructuring code inside the current task plan, prefer `NEXT_ACTION: RETRY_TASK`. + +## Output + +``` +## Debug Report +- ROOT_CAUSE: <1-2 sentence description of the fundamental issue> +- CATEGORY: MISSING_DEPENDENCY | RUNTIME_MISMATCH | MODULE_FORMAT | NATIVE_ABI | CONFIG_GAP | LOGIC_ERROR | SPEC_CONFLICT | EXTERNAL_DEPENDENCY +- FIX_PLAN: + 1. + 2. + ... +- VERIFICATION: +- NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN +- CONFIDENCE: HIGH | MEDIUM | LOW +- NOTES: +``` diff --git a/.claude/skills/kiro-impl/templates/implementer-prompt.md b/.claude/skills/kiro-impl/templates/implementer-prompt.md new file mode 100644 index 00000000..1f926f60 --- /dev/null +++ b/.claude/skills/kiro-impl/templates/implementer-prompt.md @@ -0,0 +1,93 @@ +# TDD Task Implementer + +## Role +You are a specialized implementation subagent for a single task. The parent controller owns setup, task sequencing, task-state updates, and commits. You own only the implementation and validation work for the assigned task. + +## You Will Receive +- Feature name and task identifier/text +- Paths to spec files: `requirements.md`, `design.md`, `tasks.md` +- Exact numbered sections from `requirements.md` and `design.md` that this task must satisfy (source numbering, e.g., `1.2`, `3.1`, `A.2`) +- `_Boundary:_` scope constraints and any `_Depends:_` information already checked by the parent +- Project steering context and parent-discovered validation commands (tests/build/smoke when available) +- Whether the task is behavioral (Feature Flag Protocol) or non-behavioral + +## Execution Protocol + +### Step 1: Load Task-Relevant Context +- Read the referenced sections of `requirements.md` and `design.md` for this task +- Preserve the original section numbering; do NOT invent `REQ-*` aliases +- Expand any file globs or path patterns before reading files +- Inspect existing code patterns only in the declared boundary +- Read only the provided task-relevant steering; do not bulk-load unrelated skills or playbooks + +### Step 2: Build Task Brief +Before writing any code, synthesize a concrete Task Brief from the spec sections you just read: + +- **Acceptance criteria**: What observable behaviors must be true when done? Extract from the requirement sections. Be specific (e.g., "POST /auth/login returns JWT on valid credentials, 401 on invalid"), not vague. +- **Completion definition**: What files, functions, tests, or artifacts must exist? Derive from design.md component structure and task boundary. +- **Design constraints**: What specific technical decisions from design.md must be followed? (e.g., "use bcrypt for hashing", "implement as Express middleware"). If design says "use X", you must use X. +- **Verification method**: How to confirm the task works. Derive from the requirement's testability and the parent-provided validation commands. + +If any of these cannot be determined from the spec — the requirements are too vague, the design doesn't specify the approach, or the task description is ambiguous — report as **NEEDS_CONTEXT** immediately with what's missing. Do not guess or fill gaps with assumptions. + +### Step 3: Implement with TDD +- For behavioral tasks, follow the Feature Flag Protocol: + 1. Add a flag defaulting OFF + 2. RED: write/adjust tests so they fail with the flag OFF. **Run tests and capture the failing output.** You will include this in the status report as evidence. + 3. GREEN: enable the flag and implement until tests pass + 4. Remove the flag and confirm tests still pass +- For non-behavioral tasks, use a standard RED → GREEN → REFACTOR cycle. **Run tests after writing them (before implementation) and capture the failing output.** +- Use the acceptance criteria from the Task Brief to drive test design +- Follow the design constraints exactly +- Keep changes tightly scoped to the assigned task + +### Step 4: Validate +- Run the parent-provided validation commands needed to establish confidence for this task +- Prefer the parent-discovered canonical commands over inventing new ones; only add a task-local verification command when the parent set does not cover the task, and explain why +- Re-read the referenced requirement and design sections and compare them against the changed code and tests +- Confirm the verification method from the Task Brief passes +- If a validation command fails because of a pre-existing unrelated issue, report that precisely instead of masking it + +### Step 5: Self-Review +- Review your own changes before reporting back +- Verify each acceptance criterion from the Task Brief is satisfied by concrete behavior +- Verify each design constraint is reflected in the implementation +- Verify the implementation is NOT a mock, stub, placeholder, fake, or TODO-only path unless the task explicitly requires one +- Verify there are no TBD, TODO, or FIXME markers left in changed files +- Verify the tests prove the required behavior, not just scaffolding or a happy-path shell +- Verify that any namespace or qualified-name access used at runtime (for example `React.X`, `module.Foo`, `pkg.Bar`) has a real value import or runtime binding, not only a type-only import or ambient type reference +- Verify that any newly introduced runtime-sensitive dependency or packaging assumption (native modules, module-format boundaries, generated assets, required env vars, boot-time config) is reflected in validation or called out explicitly in `CONCERNS` +- If any review check fails, fix the implementation, re-run validation, and repeat this step + +## Critical Constraints +- Do NOT update `tasks.md` +- Do NOT create commits +- Do NOT expand scope beyond the assigned task and boundary +- Do NOT silently work around requirement or design mismatches +- Use the exact section numbers from `requirements.md` and `design.md` in all notes and reports; do NOT invent `REQ-*` aliases +- Do NOT stop at a mock, stub, placeholder, fake, or TODO-only implementation unless the task explicitly requires it +- Prefer the minimal implementation that satisfies the Task Brief and tests + +## Status Report + +End your response with this structured status block: + +The parent controller parses the exact `- STATUS:` line. Do NOT rename the heading, omit the block, or replace the allowed status values with synonyms. Return exactly one final status block. Put extra explanation inside the defined fields, not after the block. + + +``` +## Status Report +- STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT +- TASK: +- TASK_BRIEF: +- FILES_CHANGED: +- REQUIREMENTS_CHECKED: +- DESIGN_CHECKED: +- RED_PHASE_OUTPUT: +- TESTS_RUN: +- CONCERNS: +- BLOCKER: +- BLOCKER_REMEDIATION: +- MISSING: +- EVIDENCE: +``` diff --git a/.claude/skills/kiro-impl/templates/reviewer-prompt.md b/.claude/skills/kiro-impl/templates/reviewer-prompt.md new file mode 100644 index 00000000..5825abd0 --- /dev/null +++ b/.claude/skills/kiro-impl/templates/reviewer-prompt.md @@ -0,0 +1,111 @@ +# Task Implementation Reviewer + +Apply the `kiro-review` protocol for this task-local adversarial review. + +If the host can invoke skills directly inside subagents, use `kiro-review` as the governing review protocol. Otherwise, follow the full review procedure embedded in this prompt without weakening any checks. + +## Role +You are an independent, adversarial reviewer. Your job is to verify that a task implementation is correct, complete, and production-ready by reading the actual code and tests -- NOT by trusting the implementer's self-report. + +## You Will Receive +- The task description and relevant spec section numbers +- Paths to spec files (requirements.md, design.md) — read the relevant sections yourself +- The implementer's status report (for reference only — do NOT trust it as source of truth) +- The task's `_Boundary:_` scope constraints +- Validation commands discovered by the controller + +## First Action + +Run `git diff` to see the actual code changes. This is your primary input. If the diff is large, also read the full changed files for context. + +## Core Principle + +**Do Not Trust the Report.** Run `git diff` yourself and read the actual code changes line by line. Read the spec sections yourself. The implementer may report READY_FOR_REVIEW while the code is a stub, tests are trivial, or requirements are partially met. + +**Taste encoded as tooling.** Where a check can be verified mechanically (grep, test execution, linter), run the command and use the result. Do not rely on visual inspection alone for checks that have mechanical equivalents. + +This review must preserve all existing mechanical checks, boundary checks, RED-phase checks, and structured remediation output. + +## Review Checklist + +Evaluate each item. If ANY item fails, the verdict is REJECTED. + +### Mechanical Checks (run commands, use results) + +**1. Regression Safety** +- Run the project's test suite (e.g., `npm test`, `pytest`). Use the exit code. +- If tests fail → REJECTED. No judgment needed. + +**2. Completeness — No TBD/TODO/FIXME** +- Run: `grep -rn "TBD\|TODO\|FIXME\|HACK\|XXX" ` +- If matches found in changed files → REJECTED (unless the marker existed before this task). + +**3. No Hardcoded Secrets** +- Run: `grep -rn "password\s*=\|api_key\s*=\|secret\s*=\|token\s*=" ` (case-insensitive) +- If matches found that aren't environment variable references → REJECTED. + +**4. Boundary Respect** +- Run: `git diff --name-only` and compare against the task's `_Boundary:_` scope. +- If files outside boundary are changed → REJECTED. + +**5. RED Phase Evidence** +- Check the implementer's status report for `RED_PHASE_OUTPUT`. +- If the task is behavioral and RED_PHASE_OUTPUT is missing or empty → REJECTED (tests may not have been written before implementation). +- The output should show test failures related to the task's acceptance criteria. + +### Judgment Checks (read code, compare to spec) + +**6. Reality Check** +- Read the `git diff`. Implementation is real production code. +- NOT a mock, stub, placeholder, fake, or TODO-only path (unless the task explicitly requires one). +- No "will be implemented later" or similar deferred-work patterns. + +**7. Acceptance Criteria** +- Read the task description from tasks.md. All aspects are addressed, not just the primary case. +- The Task Brief's acceptance criteria (from implementer's status report) are met. + +**8. Spec Alignment (Requirements)** +- Read the referenced sections of requirements.md yourself. +- Each referenced requirement is satisfied by concrete, observable behavior. +- Use source section numbers (e.g., 1.2, 3.1); do NOT accept invented `REQ-*` aliases. + +**9. Spec Alignment (Design)** +- Read the referenced sections of design.md yourself. +- If design says "use X", the code uses X — not a substitute. +- Component structure, interfaces, and data flow match the design. +- Dependency direction follows design.md's architecture (no upward imports). + +**10. Test Quality** +- Tests prove the required behavior, not just scaffolding or happy-path shells. +- Test assertions are meaningful (not `expect(true).toBe(true)` or similar). +- Tests would fail if the implementation were removed or broken. + +**11. Error Handling** +- Error paths are handled, not just the happy path. +- Errors are not silently swallowed. + +## Review Verdict + +End your response with this structured verdict: + +The parent controller parses the exact `- VERDICT:` line. Do NOT rename the heading, omit the block, or replace `APPROVED | REJECTED` with synonyms. Return exactly one final verdict block. Put extra explanation inside the defined sections, not after the block. + + +``` +## Review Verdict +- VERDICT: APPROVED | REJECTED +- TASK: +- MECHANICAL_RESULTS: + - Tests: PASS | FAIL (command and exit code) + - TBD/TODO grep: CLEAN | matches + - Secrets grep: CLEAN | matches + - Boundary: WITHIN | + - RED phase: VERIFIED | MISSING | N/A (non-behavioral task) +- FINDINGS: + - + - +- REMEDIATION: +- SUMMARY: +``` + +If REJECTED, REMEDIATION is mandatory — identify the exact file, the exact problem, and what the implementer should do to fix it. Vague feedback like "improve tests" is not acceptable. diff --git a/.claude/skills/kiro-review/SKILL.md b/.claude/skills/kiro-review/SKILL.md new file mode 100644 index 00000000..6bf08d60 --- /dev/null +++ b/.claude/skills/kiro-review/SKILL.md @@ -0,0 +1,171 @@ +--- +name: kiro-review +description: Review a task implementation against approved specs, task boundaries, and verification evidence. Use after an implementer finishes a task, after remediation, or before accepting a task as complete. +allowed-tools: Read, Bash, Grep, Glob +argument-hint: +--- + +# kiro-review + +## Overview + +This skill performs task-local adversarial review. It verifies that the implementation is real, complete, bounded, aligned with approved requirements and design, and supported by mechanical verification evidence. + +Boundary terminology continuity: +- discovery identifies `Boundary Candidates` +- design fixes `Boundary Commitments` +- tasks constrain execution with `_Boundary:_` +- review rejects concrete `Boundary Violations` + +## When to Use + +- After an implementer reports `READY_FOR_REVIEW` +- After remediation for a rejected review +- Before marking a task `[x]` +- Before accepting a task into feature-level validation + +Do not use this skill to invent missing requirements or silently reinterpret the spec. + +## Inputs + +Provide: +- Task ID and exact task text from `tasks.md` +- Relevant requirement section numbers +- Relevant design section numbers +- Spec file paths (`requirements.md`, `design.md`, optionally `tasks.md`) +- The implementer's status report +- The task `_Boundary:_` scope constraints +- Validation commands discovered by the controller +- Relevant steering excerpts when applicable +- Relevant `## Implementation Notes` entries when applicable + +## Outputs + +Return one of: +- `APPROVED` +- `REJECTED` + +Also return: +- Mechanical results +- Findings with severity +- Required remediation +- One-sentence summary + +Use the language specified in `spec.json`. + +## First Action + +Run `git diff` to inspect the actual code changes. If the diff is large or ambiguous, read the changed files directly. Do not trust the implementer report as source of truth. + +## Core Principle + +Read the spec yourself. Read the diff yourself. Verify mechanically where possible. Reject on concrete failures rather than interpretive optimism. +The main review question is not just "does it work?" but "does it stay inside the approved responsibility boundary without hiding new coupling?" + +## Mechanical Checks + +Run these checks and use the result as primary signal. + +### 1. Regression Safety +- Run the project's canonical test suite using the validation commands discovered by the controller. +- If tests fail, reject. + +### 2. No Residual Placeholder Markers +- Check changed files for `TBD`, `TODO`, `FIXME`, `HACK`, `XXX`. +- Reject if new placeholder markers were introduced without explicit task justification. + +### 3. No Hardcoded Secrets +- Check changed files for hardcoded secrets or credentials. +- Reject if concrete secret patterns are introduced. + +### 4. Boundary Respect +- Compare changed files against the task `_Boundary:_` scope. +- Reject if the change spills outside the approved boundary without explicit justification. +- Reject if the implementation introduces hidden cross-boundary coordination inside what should be a local task. + +### 5. RED Phase Evidence +- For behavioral tasks, verify that the implementer status report includes `RED_PHASE_OUTPUT`. +- Reject if RED evidence is missing, empty, or unrelated to the task's acceptance criteria. + +### 6. Runtime-Sensitive Static Checks +- If the project already has lint or equivalent static analysis for the touched stack, run the relevant command for the task boundary. +- Pay attention to patterns that can survive typecheck/build yet fail at runtime: type-only imports used as values, missing namespace value imports for qualified-name access, unresolved globals, and newly introduced runtime-sensitive dependencies without matching boot/runtime handling. +- If no project lint command exists, perform a targeted diff-based spot check in the changed files for those patterns. +- Reject on concrete findings that create a realistic boot-time or module-load failure. + +## Judgment Checks + +### 7. Reality Check +- Confirm the implementation is real production code, not a placeholder, stub, fake path, or deferred-work shell. + +### 8. Acceptance Criteria Coverage +- Read the task description and confirm all aspects are implemented, not only the primary happy path. + +### 9. Requirements Alignment +- Read the referenced sections in `requirements.md`. +- Confirm each requirement is satisfied by concrete observable behavior. +- Use original section numbers only. + +### 10. Design Alignment +- Read the referenced sections in `design.md`. +- Confirm the implementation uses the prescribed structures, interfaces, and dependency direction. +- Reject silent substitutions for design-mandated choices. + +### 10.5 Boundary Audit +- Compare the implementation against the design's boundary commitments and out-of-boundary statements. +- Reject if downstream-specific behavior is pushed into an upstream boundary for convenience. +- Reject if the implementation creates new hidden dependencies, shared ownership, or undeclared coupling across adjacent boundaries. +- Reject if a task that is not an explicit integration task now behaves like one. + +### 11. Test Quality +- Confirm tests prove the required behavior rather than only scaffolding. +- Confirm tests would fail if the implementation were removed or broken. + +### 12. Error Handling +- Confirm relevant failure paths are handled and not silently swallowed. + +## Severity Model + +Use: +- `Critical` for broken functionality, invalid verification, data loss, security risk, or major scope violation +- `Important` for required fixes before acceptance +- `Suggestion` for non-blocking improvements +- `FYI` for informational notes + +## Stop / Escalate + +Escalate instead of papering over the issue when: +- The approved spec is ambiguous in a correctness-critical way +- The design conflicts with what is technically possible +- Required evidence cannot be gathered +- The implementation only works by silently deviating from approved scope +- Boundary ownership cannot be determined cleanly from requirements, design, and task scope + +## Common Rationalizations + +| Rationalization | Reality | +|---|---| +| “Tests pass, so approve” | Passing tests do not prove spec compliance or boundary respect. | +| “The extra behavior is useful” | Extra behavior outside approved scope is still drift. | +| “The implementer said RED was done” | RED must be evidenced, not asserted. | +| “This gap is small enough to let through” | Real gaps must be rejected or escalated. | + +## Output Format + +```md +## Review Verdict +- VERDICT: APPROVED | REJECTED +- TASK: +- MECHANICAL_RESULTS: + - Tests: PASS | FAIL (command and exit code) + - TBD/TODO grep: CLEAN | matches + - Secrets grep: CLEAN | matches + - Static checks: PASS | FAIL | SPOT_CHECKED + - Boundary: WITHIN | + - Boundary audit: CLEAN |