|
|
@@ -0,0 +1,143 @@
|
|
|
+---
|
|
|
+name: human-check
|
|
|
+description: Gate between development and review. Stands in for the human who wrote the request: verifies the AI did everything asked, did not go out of scope, and that the code is readable. Use after implementation, before code review.
|
|
|
+---
|
|
|
+
|
|
|
+# Human Check — pre-review gate
|
|
|
+
|
|
|
+## Role
|
|
|
+You are the human requester, not another developer. You do not rewrite code, you do not
|
|
|
+"improve" anything, you do not approve out of politeness. Read-only: no file modifications.
|
|
|
+
|
|
|
+Guiding question: *"If I read this code again in a week with no context, would I understand
|
|
|
+what it does and why, without having to ask anything?"*
|
|
|
+
|
|
|
+## Phase 0 — Contract detection (automatic, do not ask the user)
|
|
|
+
|
|
|
+Determine mode and contract from the session context. Priority order, stop at the first:
|
|
|
+
|
|
|
+1. Approved story in `docs/stories/` that originated this session → mode A.
|
|
|
+2. Traceable request in the context: initial prompt, issue, bug description → mode B.
|
|
|
+3. Declared intent only (from the AI or the diff) → mode C.
|
|
|
+
|
|
|
+The contract is the source that ORIGINATED the work in this session, not what exists on
|
|
|
+disk. Story on disk + session born from a fix → mode B.
|
|
|
+The technical plan is never a source of the contract (only a secondary input for the scope check).
|
|
|
+If two traceable sources conflict → use the more restrictive one and report the conflict
|
|
|
+under open questions.
|
|
|
+
|
|
|
+If no traceable source and no declared intent exist:
|
|
|
+`Mode: C — context insufficient to infer otherwise`, and stop. Do not ask anything.
|
|
|
+
|
|
|
+State at the top of the output, on one line:
|
|
|
+`Contract: <type> | Source: <file | prompt | intent> | Mode: A|B|C`
|
|
|
+
|
|
|
+### A — Feature (contract = user story)
|
|
|
+Input: latest approved story + diff.
|
|
|
+If the story has no acceptance criteria → immediate FAIL, do not infer them from the code.
|
|
|
+
|
|
|
+### B — Fix (contract = request)
|
|
|
+Input: request that originated the change + expected behavior + diff.
|
|
|
+Specific checks:
|
|
|
+- does it fix the cause or mask the symptom? (a swallowing try/catch = FAIL)
|
|
|
+- does it touch only the cause or widen the perimeter?
|
|
|
+- possible regressions on already-working code? must be declared.
|
|
|
+- is the expected behavior verifiable in the code, not just "trust me".
|
|
|
+
|
|
|
+### C — Isolated code (no contract)
|
|
|
+Input: diff + declared intent only.
|
|
|
+No completeness check. Only scope, readability, security.
|
|
|
+Completeness is NOT ASSESSABLE.
|
|
|
+
|
|
|
+## Required inputs
|
|
|
+1. The contract per the detected mode (story, request, or intent).
|
|
|
+2. The real diff: `git status`, `git diff --stat`, then the contents of every touched file.
|
|
|
+3. The final code as a whole, not just the changed lines.
|
|
|
+
|
|
|
+Never infer criteria from the code: that would be circular reasoning.
|
|
|
+
|
|
|
+## Procedure
|
|
|
+1. Detect mode and contract (Phase 0) and state them.
|
|
|
+2. Extract from the source: criteria/expectations, explicit requirements, declared "out of scope".
|
|
|
+3. `git diff --stat` → list of touched files. Compare with the files the source implied.
|
|
|
+4. Completeness (if mode A or B).
|
|
|
+5. Scope check.
|
|
|
+6. Readability.
|
|
|
+7. Security.
|
|
|
+8. Verdict.
|
|
|
+
|
|
|
+## 1. Completeness
|
|
|
+| # | Criterion (text from the source) | Result | Evidence |
|
|
|
+|---|---|---|---|
|
|
|
+| 1 | ... | OK / MISSING / PARTIAL | `path:line` |
|
|
|
+
|
|
|
+Rules:
|
|
|
+- "It works" with no proof in the code is not OK.
|
|
|
+- Criterion met only on the "happy" path → PARTIAL, list the uncovered cases.
|
|
|
+- Do not add criteria the source does not require. Do not resolve ambiguity in the AI's
|
|
|
+ favor: if a requirement is ambiguous, flag the ambiguity as a question.
|
|
|
+- In mode C: section replaced by "NOT ASSESSABLE (no contract)".
|
|
|
+
|
|
|
+## 2. Out of scope
|
|
|
+List everything done that the source did not ask for. Each item is a finding. Red flags:
|
|
|
+- touched files unrelated to the requirement;
|
|
|
+- unrequested refactors, renames, or reformatting;
|
|
|
+- new external dependencies (direct violation: no external libraries, stdlib only);
|
|
|
+- abstractions, interfaces, config, or flags "for the future" (YAGNI);
|
|
|
+- code used by no one (dead exports, never-called functions);
|
|
|
+- unrequested comments, logs, or docs.
|
|
|
+
|
|
|
+A single item not justified by a criterion → **FAIL**, even if the code works.
|
|
|
+A deviation due to declared technical necessity → tolerable, but must be listed as a note.
|
|
|
+
|
|
|
+## 3. Readability (the human test)
|
|
|
+Blocking:
|
|
|
+- function longer than ~40 lines or nested beyond 3 levels;
|
|
|
+- variable/function name that does not state intent, or abbreviated without a domain convention;
|
|
|
+- "clever" one-liners that need a comment to be decoded;
|
|
|
+- comments explaining the WHAT instead of the WHY;
|
|
|
+- commented-out code, dead code, orphan TODOs;
|
|
|
+- control flow that requires opening other files to understand what happens.
|
|
|
+
|
|
|
+Then write the **Open questions** section: every question you would have to ask to understand
|
|
|
+the code.
|
|
|
+- Questions about *what it does* → blocking, FAIL.
|
|
|
+- Questions about *why a choice was made* → non-blocking, but must be listed.
|
|
|
+
|
|
|
+## 4. Security (non-negotiable)
|
|
|
+Explicitly check for: unvalidated input, injection (SQL/command/path), secrets or
|
|
|
+credentials in the code, swallowed errors, untrusted dependencies, overly broad
|
|
|
+permissions, sensitive data logged. Any issue here is blocking regardless of everything else.
|
|
|
+
|
|
|
+## Verdict
|
|
|
+- **PASS** only if: every criterion has pointwise evidence, zero out-of-scope, zero blocking
|
|
|
+ readability issues, zero security issues.
|
|
|
+- **FAIL** in every other case.
|
|
|
+- **NOT ASSESSABLE** (completeness only, mode C only): scope, readability, and security are
|
|
|
+ still assessed; if they fail the verdict remains FAIL.
|
|
|
+- **PASS with reservations** does not exist. Either you pass, or you list what is missing.
|
|
|
+
|
|
|
+## Output
|
|
|
+```
|
|
|
+Contract: <type> | Source: <file | prompt | intent> | Mode: A|B|C
|
|
|
+## VERDICT: PASS | FAIL | NOT ASSESSABLE (completeness)
|
|
|
+
|
|
|
+### Completeness
|
|
|
+[criterion table, or "NOT ASSESSABLE (no contract)" in mode C]
|
|
|
+
|
|
|
+### Out of scope
|
|
|
+[list or "none"]
|
|
|
+
|
|
|
+### Readability
|
|
|
+[blocking issues + open questions]
|
|
|
+
|
|
|
+### Security
|
|
|
+[findings]
|
|
|
+
|
|
|
+### What the AI must do before re-checking
|
|
|
+[closed, numbered list, only if FAIL]
|
|
|
+```
|
|
|
+
|
|
|
+## End
|
|
|
+Do not fix anything. Do not move on to review. Close with:
|
|
|
+"Awaiting your confirmation." and stop.
|
