@mrciphersmith/keryx 0.2.98 → 0.2.99

package/src/gdskills/bundled/skills/planning/autodoc-analyst/SKILL.md

@@ -5,6 +5,10 @@ description: >
   to extract purpose, structure, public API surface, patterns, and key dependencies.
   Use when: dispatched by autodoc-orchestrator Phase 2 (one instance per module).
   NOT for: direct user invocation.
+triggers:
+  - "autodoc analyst"
+  - "analyze module docs"
+  - "reverse engineer module"
 metadata:
   version: 1.0.0
 ---
@@ -26,6 +30,18 @@ and writers can use without re-reading the source code.
 | 4 | Document what the code DOES, not how it does it internally |
 | 5 | Extract concrete examples from code (real function names, real endpoints) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This module imports from the shared module, so I should analyze that too." | Iron Law 1: one module per invocation. Another analyst has `shared` and is reading it right now. Record the dependency as a dependency; analysing across the boundary duplicates their work and produces two disagreeing accounts of the same code. |
+| "The framework's conventions tell me what this service does." | Iron Law 2: understanding comes from the code in front of you. A NestJS service named `UserService` does whatever this repository made it do, and the convention-based description is the one no reader can catch as wrong. |
+| "This internal helper is the clever part, so it deserves the most detail." | Iron Law 3 and 4: public interfaces first, and document what the module DOES, not how. Internals change without notice; the exported surface is what the writers and the architect can actually build on. |
+| "A real endpoint list would be long — a representative example is clearer." | Iron Law 5 asks for concrete names from the code. A representative example is indistinguishable from an invented one to everyone downstream, and Phase 4 will publish it as if it were real. |
+| "The entry point isn't where project-map said — I'll analyze what I can find." | That mismatch is exactly what `NEEDS_CONTEXT` (and `concerns`) exist for. Quietly analysing a different starting point produces an artifact the architect will merge without knowing it describes something else. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-architect/SKILL.md

@@ -7,6 +7,10 @@ description: >
   points, and cross-cutting concerns.
   Use when: dispatched by autodoc-orchestrator Phase 3.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc architect"
+  - "architecture docs"
+  - "reverse engineer architecture"
 metadata:
   version: 1.0.0
 ---
@@ -28,6 +32,18 @@ fit together — something no single module analyst can see alone.
 | 3 | Map ALL cross-module interactions found in the analyses |
 | 4 | Identify the system's architectural style (what it IS, not what it should be) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "One analysis file is thin — the others are enough to see the shape." | Iron Law 1: every module analysis is read, none ignored. The thin one is usually the integration edge (infra, shared, a worker) whose absence turns a real topology into a tidy diagram of the parts you liked. |
+| "This looks like clean architecture, so the layers are the usual four." | Iron Law 4: describe what the system IS. A named style imported from outside the evidence makes the document describe a project the reader does not have, and every later doc inherits it. |
+| "The frontend obviously calls the backend — that interaction needs no evidence." | Iron Law 2 and 3: every cross-module interaction is derived from something an analysis actually reported. "Obviously" is where a message queue, a BFF, or a direct database read from the frontend disappears from the map. |
+| "The analyses contradict each other about this contract, so I'll pick the more plausible one." | A contradiction is a finding. Record it in `concerns` and return `DONE_WITH_CONCERNS`. Choosing silently buries the one thing the module analysts could not see and you can. |
+| "The architecture is clear to me, so the document can stay at a high level." | The writers in Phase 4 have only this file for anything spanning modules. A high-level summary without data flows and integration points means the architecture section is written from the same summary, twice. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-assembler/SKILL.md

@@ -5,6 +5,10 @@ description: >
   into a cohesive package: main README.md and navigation index.
   Use when: dispatched by autodoc-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc assemble"
+  - "assemble docs"
+  - "assemble documentation package"
 metadata:
   version: 1.0.0
 ---
@@ -25,6 +29,18 @@ verify cross-references, write the main README and navigation index.
 | 3 | All cross-links between docs must use relative paths |
 | 4 | Do NOT repeat content from sections — summarize and link |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I know what `api-reference.md` contains from its name — no need to open it." | Iron Law 1: read every section before writing. A writer that returned `DONE_WITH_CONCERNS` may have left a half-written file or a [TODO]; the index would then link confidently to a page that does not deliver what the link promises. |
+| "The onboarding steps are the most important thing, so I'll repeat them in the README." | Iron Law 4: summarize and link. Duplicated steps drift the moment one copy is updated, and the reader has no way to tell which copy is current. |
+| "An absolute path works on my machine and is unambiguous." | Iron Law 3: relative paths only. The docs package gets moved, committed, and read from a repository checkout — an absolute path from the job directory breaks on every machine but the one that wrote it. |
+| "A writer left `[TODO: add X]`, but the section is otherwise complete." | Those TODOs are what `concerns` is for. The orchestrator's final report is the only place the user learns the documentation has known holes; an assembler that filters them out reports a complete package that is not. |
+| "A section is missing from `docs/`, so it must not have been needed." | A missing file means a Phase 4 writer failed or was never dispatched. Report it as a concern — inferring intent from an absence is how a documentation package quietly ships without its API reference. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -8,6 +8,8 @@ description: >
   NOT for: writing new PRDs or planning new features (use gproject-orchestrator).
 triggers:
   - "autodoc"
+  - "document codebase"
+  - "reverse engineer docs"
   - "автодок"
   - "document this codebase"
   - "generate docs for my project"
@@ -55,6 +57,21 @@ emit it when dispatched as a subagent.
 
 ---
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The subagent's response summarized its findings, so the phase is complete." | Iron Law 3 requires an artifact FILE. The next phase reads `artifacts/analysis/*.md`, not your transcript — a phase whose file is missing produces a downstream subagent documenting nothing. Check the path exists before advancing. |
+| "This module is tiny — faster to describe it myself than to dispatch an analyst." | Iron Laws 1 and 2 have no size exception. The moment the orchestrator writes content, the pipeline has one unreviewed author whose output no artifact backs, and the parallel structure silently becomes serial guesswork. |
+| "The scanner found 12 modules; I'll analyze the important ones and cover the rest later." | Phase 2 is one analyst per detected module, launched together, and Phase 3 waits for all of them. A partial analysis set yields an architecture doc that describes a system missing several of its parts, with nothing marking the omission. |
+| "A writer came back DONE_WITH_CONCERNS, but the file looks fine, so I'll drop the concern." | `DONE_WITH_CONCERNS` exists so the concern reaches the user. It goes into `state.json` and into the Final Report's `Concerns` line. A dropped concern is indistinguishable from a clean run. |
+| "The subagent asked for context twice — I know this repo, I'll answer from memory." | Iron Law 1 again: answering from your own reading of the code is the orchestrator reading code. Resolve from artifacts or a dispatched collector; after two rounds, ask the user with A/B/C/D options. |
+| "There is an interrupted job in `jobs/`, but starting fresh is cleaner." | State Resumption is the user's call, offered as A/B/C. Starting fresh silently discards completed phases they paid for and may overwrite `docs/` files they have already read. |
+
+---
+
 ## Pipeline Overview
 
 ```

package/src/gdskills/bundled/skills/planning/autodoc-scanner/SKILL.md

@@ -5,6 +5,10 @@ description: >
   detects stack, identifies module boundaries, entry points, and dependencies.
   Use when: dispatched by autodoc-orchestrator Phase 1.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc scan"
+  - "scan codebase"
+  - "documentation targets"
 metadata:
   version: 1.0.0
 ---
@@ -25,6 +29,18 @@ and writers can rely on without re-scanning the codebase.
 | 3 | Always list entry points (main files, index files, app bootstraps) |
 | 4 | Return module list in `next_phase_hints.modules[]` — orchestrator uses this to spawn analysts |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "These two packages are small — I'll list them as one module." | Phase 2 spawns exactly one analyst per entry in `next_phase_hints.modules[]`. A merged entry gives one analyst two codebases and leaves a module nobody documents under its own name. |
+| "`package.json` is ambiguous about the framework, so I'll read the source to be sure." | Iron Law 1: directory listings and targeted config reads only. An unknown framework is reported as unknown — reading source here does Phase 2's job with a Phase 1 budget, and the analyst will read it properly anyway. |
+| "These directories are named like features, so they are modules." | Iron Law 2: boundaries come from directory structure AND build config. Names alone invent modules the build system does not have, and each invented one costs a full analyst dispatch. |
+| "There is no `openapi.yaml`, so `has_api` is false." | Step 5 lists five independent signals, any one of which is sufficient. A false from checking one of them tells Phase 4 not to write an API reference for a project that has an API. |
+| "The main app's entry point is obvious — one entry is enough." | Iron Law 3 asks for entry points per module. An analyst handed a module with no entry point starts from the directory listing and guesses at what bootstraps it. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-writer/SKILL.md

@@ -5,6 +5,10 @@ description: >
   from analysis artifacts. Dispatched in parallel — one instance per section.
   Use when: dispatched by autodoc-orchestrator Phase 4.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc writer"
+  - "write docs"
+  - "generate documentation pages"
 metadata:
   version: 1.0.0
 ---
@@ -26,6 +30,18 @@ for one specific section. Each instance handles exactly one output file.
 | 4 | Use concrete examples from the actual codebase (real file paths, real commands) |
 | 5 | If a section requires info not in the artifacts, note it as [TODO: add X] rather than inventing |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The artifacts don't give the install command, but `npm install` is always right." | Iron Law 2 and 5: write `[TODO: add install command]` instead. A plausible command in an onboarding doc is worse than a gap — the new developer runs it, it fails, and they stop trusting the rest of the page. |
+| "This belongs in the architecture section too, so I'll cover it here as well." | Iron Law 1: one section per invocation. Another writer owns that section right now, and two independently written accounts of the same thing will not agree by the time the assembler links them. |
+| "A generic example reads more cleanly than the real file path." | Iron Law 4 requires real paths and real commands. `src/foo/bar.ts` teaches nothing and cannot be checked; the actual path is the part the reader copies. |
+| "The API section is for developers, so more implementation detail is better." | Iron Law 3: write for the section's audience. API consumers need the contract — request, response, errors — not the service internals, which change without any promise to them. |
+| "I left a few TODOs, but the section reads as finished, so `DONE`." | Every gap goes into `concerns`, and a section held together by TODOs is `DONE_WITH_CONCERNS`. The assembler collects those TODOs in Phase 5; one that never reached `concerns` ships as finished documentation. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/brainstorm/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: brainstorm
-description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives."
+description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
 triggers:
-  - "/brainstorm"
-  - "Brainstorm"
+  - "brainstorm"
+  - "explore options"
+  - "architecture decision"
   - "Let's think about"
   - "What are options for"
   - "How should we approach"
@@ -88,3 +89,27 @@ Add: **Security Analyst** (auth, data exposure, compliance) and **UX Advocate**
 - The Critic's questions must be answered by the recommendation
 - Don't dismiss "boring" solutions — they often win
 - End with concrete next steps, not just analysis
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "All three agents converged on the same option, so it must be right." | Three agents given one framing usually converge because the framing already decided it. Convergence is evidence about the prompt, not about the option. Check whether all three skipped the same constraint before calling agreement a result. |
+| "The best option is obvious, so the comparison matrix is busywork." | The matrix is the only part the user can audit. Without effort, risk and time-to-ship side by side, "recommended" is an assertion they have to take on trust — and the obvious option is exactly the one whose cost nobody checked. |
+| "The Critic raised risks, but they apply to the runner-up, not my pick." | The Critic's questions apply to ALL options by construction. The recommendation must answer each one or explicitly accept it as a known risk. Silently routing a question to the option you did not pick is how the risk ships. |
+| "This is early exploration, so effort estimates would be premature." | An idea without an estimate is not actionable, which is the whole output of this skill. A labelled guess (S/M/L, stated as a guess) is usable; no number is not. |
+| "The innovative option is more interesting, so it is the better recommendation." | Novelty is not a criterion in the matrix. If the boring option scores better on effort, risk and time to ship, it wins — say so, and put the interesting one in the runner-up slot with the condition that would flip the call. |
+
+## Verification
+
+Before reporting, all of these must hold:
+
+- The Ideas Map has at least two distinct options, each with approach, pros, cons, effort (S/M/L) and risk.
+- The comparison matrix has one column per option and a row per criterion — no blank cells.
+- Every Critical Question from the Critic is listed, and the recommendation either answers it or names it as an accepted risk.
+- The recommendation names a runner-up and the specific condition under which the runner-up would be chosen instead.
+- Next steps are concrete actions, each specific enough to become a task — not "investigate further".
+- In `--quick` mode: 3-5 scored options in a table and one recommendation. In `--deep` mode: the Security Analyst and UX Advocate perspectives both appear in the synthesis, not just in the agent output.
+- Options are grounded in the project's actual stack and constraints; anything assumed about the stack is labelled as an assumption.

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.codex.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.cursor.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
 ---
@@ -28,6 +32,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -2,11 +2,15 @@
 name: docpack-orchestrator
 description: "Use when creating or updating a Metaproject requirements package under docs/requirements: PRD, specification, README, policies/protocols/schemas, roadmap updates, verification, and package review. Use for requests like 'create requirements package', 'prepare module documentation', 'write PRD/spec for module', or 'оформи пакет документации'. Not for reverse-engineering current codebase documentation; use autodoc-orchestrator for that."
 triggers:
-  - "create requirements package"
   - "requirements package"
+  - "create requirements package"
+  - "module documentation"
+  - "documentation package for implementation"
+  - "пакет документации"
+  - "оформи пакет документации"
+  - "подготовь пакет документации"
   - "prepare module documentation"
   - "write PRD and spec"
-  - "оформи пакет документации"
   - "создай документацию модуля"
 metadata:
   author: "MrCipherSmith"
@@ -129,6 +133,32 @@ Run a local verification pass:
 Use `docpack-review` for an adversarial pass. Fix blockers before
 final output. Warnings may remain only if called out clearly.
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "README, PRD and spec agree with each other, so the implementation status is accurate." | Agreement between three documents is agreement between three documents. Iron Law 6 requires code as the proof. Open the path, or write the status as `planned`. |
+| "`docpack-review` came back with warnings only, so the package is done." | Phase 5 permits warnings to remain *only if they are called out clearly* in the Final Response. A warning that lives in the review output and not in `remaining_gaps` has been dropped, not accepted. |
+| "This package is small — a specification alone covers it." | Iron Law 4: README, PRD and specification are all required for module packages. "Small" is the most common reason a package ships with no problem statement and no document index. |
+| "I rewrote most of the doc, so the `Version` obviously moved." | Nothing bumps it for you. Iron Law 3 is checked file by file in Phase 4, and an unbumped version is what makes a stale copy indistinguishable from the current one. |
+| "The user gave me thorough notes, so Phase 1 evidence is redundant." | User notes do not contain the existing package files, `docs/requirements/roadmap.md`, or what a prior version of this package already promised. Skipping Phase 1 is how a package contradicts its own last revision. |
+| "Review is its own skill — the user can run `docpack-review` afterwards." | Iron Law 5 makes verification and review mandatory *before* final output. An unreviewed package reported as complete is the failure this pipeline exists to prevent. |
+
+## Exit Criteria
+
+Do not emit the Final Response until all of these hold:
+
+- Every required file for the package kind exists at `docs/requirements/<package_name>/`, and each was written or deliberately left unchanged — not assumed.
+- Every Markdown file in the package carries a `Version`, and every file you changed has a bumped one.
+- `README.md` links to every file in the package; the specification links to each schema it defines.
+- Every `schemas/*.json` parses as valid JSON.
+- `docs/requirements/roadmap.md` is updated when the package represents a new module or capability, or the report states why it does not.
+- No implementation claim appears that code does not support; anything unbuilt is marked planned or future.
+- `docpack-review` has been run in Phase 5 and reports zero blockers. Remaining warnings appear verbatim in `remaining_gaps`.
+- Every field of the Final Response block is filled with a real value — no placeholder, and `verification`/`review` are never reported as `pass` when the pass did not run.
+
 ## Final Response
 
 Report:

package/src/gdskills/bundled/skills/planning/docpack-review/SKILL.md

@@ -2,9 +2,8 @@
 name: docpack-review
 description: "Use when reviewing or verifying a Metaproject requirements package under docs/requirements for completeness, versioning, README/PRD/spec consistency, schema references, roadmap updates, unsupported claims, and implementation-status accuracy. Usually dispatched by docpack-orchestrator. Not for reviewing autodoc-generated current-codebase documentation."
 triggers:
-  - "review requirements package"
-  - "verify requirements package"
   - "requirements package review"
+  - "verify requirements package"
   - "check PRD spec consistency"
   - "проверь документацию"
 metadata:
@@ -62,6 +61,19 @@ Adversarial reviewer for Metaproject requirements packages.
 - Future commands are marked future/planned.
 - Integrations distinguish implemented, planned and optional.
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The three required files are clean, so the optional ones will be too." | Iron Law 1 forbids sampling. Optional files are where unsupported claims collect precisely because nobody expects them to be read — `agent-protocol.md` and `metrics-and-validation.md` describe behavior that most often does not exist yet. |
+| "The PRD and the specification both say this command exists, so the claim is supported." | Two documents agreeing is one author repeating themselves. The Accuracy checks resolve against the repository, not against a sibling doc. If no code backs the claim, it is a blocker. |
+| "The fix is one line — faster to apply it than to describe it." | Iron Law 6: report findings and suggested fixes, never rewrite. A reviewer who edits has no reviewer, and the orchestrator loses the record of what was wrong. |
+| "It is only a missing `Version` field — that is a warning, not a blocker." | Iron Law 3 names it a blocker outright, as does a missing required file (Law 2). The severity is fixed by the law, not by how small the fix looks. |
+| "There are blockers, but the package is broadly good, so `PASS_WITH_WARNINGS`." | Any blocker means `verdict: FAIL`. Softening the verdict is how a package with a missing spec reaches implementation. |
+| "The README status is stale but harmless, so it is an INFO note." | README status disagreeing with the PRD or spec is a contradiction, and Iron Law 5 makes contradictions blockers. Stale status is the field implementers read first. |
+
 ## Output
 
 Return findings first:

package/src/gdskills/bundled/skills/planning/interview/SKILL.md

@@ -1,13 +1,10 @@
 ---
 name: interview
-description: "Use to clarify implementation-specific ambiguities AFTER context has already been collected and the goal is known — the questions that sharpen a plan, not the ones that scope the request. This is the `implement`-intent interview job-orchestrator runs at 0.3. To pin down a vague request before any context is gathered, use `interviewer` instead."
+description: "Use to clarify implementation-specific ambiguities AFTER context has already been collected and the goal is known — the questions that sharpen a plan, not the ones that scope the request. This is the `implement`-intent interview job-orchestrator runs at 0.3. NOT for: pinning down a vague request before any context is gathered — use `interviewer` instead."
 triggers:
-  - "/interview"
-  - "Interview"
-  - "Clarify requirements"
-  - "Ask questions first"
-  - "What do you need to know"
-  - "Gather requirements"
+  - "implementation interview"
+  - "interview before implementation"
+  - "clarify implementation"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
@@ -185,3 +182,28 @@ The interview skill is designed to be composable — any skill that needs user i
 - ALWAYS adapt subsequent questions based on previous answers
 - If the user seems impatient or says "just do it" — stop interviewing, document remaining unknowns as assumptions, and proceed
 - One question at a time — never dump all questions at once
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "They said 'sounds good', so the whole summary is approved." | A single agreeable noise is not confirmation of a list of decisions, constraints, assumptions and risks. The Assumptions block is labelled "please verify" for a reason — if the user did not address an assumption, it stays an assumption in the output contract, not a confirmed decision. |
+| "The user said 'just do it', so I can drop the unknowns." | Impatience ends the interview; it does not resolve anything. Every remaining uncertainty zone becomes an entry in `assumptions` with the risk it carries. Dropping it hides the guess from the skill that will act on it. |
+| "This is an interesting question, so it belongs in the interview." | The bar is impact: the answer must change the implementation. Questions derivable from the codebase, or whose answers change nothing, spend the user's limited patience on nothing and push the real question past the 7-question ceiling. |
+| "The user picked D) Need more context, so this question is unanswered — move on." | D is a request, not an answer. Explain or run a mini `/brainstorm --quick` on that point, then re-ask. Silently skipping it leaves the highest-uncertainty question the least answered. |
+| "The caller gave me `context`, so I should confirm what it says with the user." | Re-asking what the context already answers is the failure the Phase 2 skip rule names. Read `context` and `known_facts` first; ask only about what neither settles. |
+| "I was dispatched as a subagent with a task, and the task is ambiguous, so I'll interview." | See the SUBAGENT-STOP block at the top: a dispatched subagent proceeds with its assigned task. There is no user on the other end of a dispatch to answer. |
+
+## Verification
+
+Before returning, all of these must hold:
+
+- The output contract has all five keys — `decisions`, `constraints`, `assumptions`, `risks`, `refined_goal` — and none is a placeholder.
+- Every entry in `decisions` carries an `impact` of `high` or `medium` and traces to a question the user actually answered.
+- Anything the user skipped, deferred, or did not address is in `assumptions`, not in `decisions`.
+- No more than 7 questions were asked, one at a time, and none duplicated what `context` or `known_facts` already stated.
+- `refined_goal` is unambiguous enough that a downstream skill could act on it without re-reading the transcript.
+- The Interview Summary was shown and the user was asked "Does this look right?" — and any correction they gave is reflected in the returned contract.
+- In standalone mode, the handoff names the next skill rather than ending with the summary.

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: interviewer
-description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. For clarifying implementation specifics AFTER context is already collected, use `interview` instead."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. NOT for: clarifying implementation specifics AFTER context is already collected — use `interview` instead."
 triggers:
+  - "ask questions"
+  - "clarify requirements"
+  - "interview"
   - "Interview me"
   - "Ask me questions"
-  - "Clarify requirements"
   - "Gather requirements"
   - "What do you need to know"
 metadata:
@@ -43,6 +45,7 @@ context?: {             — optional, provided by calling skill
 ```
 answers: [{question, answer, confidence: "certain"|"assumption"|"unknown"}]
 derived_context: string   — all gathered info as one coherent block
+summary_confidence: "certain"|"assumption"|"unknown"   — weakest confidence in answers
 ready_to_proceed: boolean
 blockers?: string[]       — unresolved critical unknowns
 ```
@@ -82,24 +85,47 @@ blockers?: string[]       — unresolved critical unknowns
 - **Skip if already known** — if context answers a question, don't ask it
 - **Be critical** — focus on questions that would change the approach
 - **Max 8 questions** — stop when enough context is gathered
-- **Confirm before proceeding** — summarize gathered context and ask if correct
+- **Confirm before proceeding** — summarize gathered context, state the summary's own confidence (the weakest of the answers it rests on), and ask if correct
 
 ## Question Bank by Goal Type
 
 ### For implementation goals
 - What is the expected input/output?
 - What are the edge cases that must be handled?
-- Are there existing similar patterns in the codebase to follow?
 - What is the performance/scale requirement?
 - What should NOT be changed (constraints)?
 
 ### For review goals
 - What specific concerns should the review focus on?
-- Are there known existing issues to watch for?
 - What is the acceptance criteria?
 
 ### For architecture/design goals
 - What are the hard constraints (performance, compat, timeline)?
-- What does success look like in 6 months?
 - What are you most worried about?
 - Who else is affected by this decision?
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "These three questions are related, so I'll ask them in one message to save time." | One question at a time is the rule, and it is not politeness. A batch gets one answer to the easiest item and silence on the rest, which you then record as if it had been answered. |
+| "The answer was vague, but I understood the gist, so `ready_to_proceed: true`." | A gist is an assumption. Either ask the follow-up, or record the item in `blockers` with `confidence: "assumption"` and leave `ready_to_proceed` false. Proceeding on a gist is exactly the wasted work this gate exists to prevent. |
+| "They said 'sure, that sounds about right', so that is a yes and `ready_to_proceed: true`." | A hedge is not a refusal and it is not approval. This is not the vague-answer case above — you understood the answer perfectly, and it committed the user to nothing. Name the hedge back ("that is a 'probably' — is it a yes?") and ask the question that forces one. If no commitment comes, the item is recorded as `confidence: "assumption"`, never as confirmation. (That a hedged agreement is not approval is adapted (MIT) from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills); naming the hedge back and the confidence enum are ours.) |
+| "I inferred the answer from the codebase, so I can mark it `certain`." | `certain` means the user said it. An inference is `assumption`, even a good one — the confidence field is the only signal downstream skills have about which parts of `derived_context` are load-bearing guesses. |
+| "I've hit the 8-question limit and still don't know, so I'll pick the likely answer." | The limit is a stop rule, not a licence to invent. Remaining unknowns go into `blockers`, `ready_to_proceed` goes false, and the caller decides. |
+| "Context-collector already ran, so anything still missing must not matter." | Collected context answers what the codebase knows, not what the user intends. Scope, priority and what must NOT change are never in the codebase, and those are the answers that change the approach. |
+| "I was dispatched as a subagent with a task, and the task is unclear, so I'll interview." | See the SUBAGENT-STOP block at the top: a dispatched subagent proceeds with its assigned task. Interviewing from inside a dispatch asks questions nobody is there to answer. |
+
+## Verification
+
+Before returning, all of these must hold:
+
+- Every entry in `answers` carries a question, an answer, and a `confidence` value from the enum — no blank or invented confidences.
+- No question was asked that the provided context already answered, and no two questions were sent in one message.
+- At most 8 questions were asked.
+- Every `assumption` or `unknown` was either resolved with a follow-up or is listed in `blockers`.
+- `summary_confidence` equals the weakest confidence in `answers`, and was stated when the summary was read back — a user approving a summary built on assumptions was told that is what they were approving.
+- `ready_to_proceed` is `false` whenever `blockers` is non-empty, and `true` only after the user confirmed the summarized context.
+- `derived_context` reads as one coherent block a downstream skill can act on, and states which of its claims are assumptions.

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.codex.md

@@ -5,6 +5,10 @@ description: >
   application architecture patterns. Produces constraints that PRD must follow.
   Use when: dispatched by gproject-orchestrator Phase 3.
   NOT for: direct user invocation.
+triggers:
+  - "research patterns"
+  - "architecture patterns"
+  - "best practices"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,18 @@ and architectural decisions for each technology. The output becomes a set of
 | 5 | Output MUST be structured as checkable constraints, not prose advice |
 | 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "Clean Architecture is the right answer for any serious project." | Iron Law 2: patterns must fit the chosen level. Layer boundaries and ports-and-adapters on an MVP buy indirection nobody has time to maintain, and Phase 4 is then bound by a constraint that slows every task. |
+| "This is standard practice, so it needs no source." | Iron Law 1: every pattern cites official docs, community consensus, or established practice. Uncited standard practice is how a convention three major versions out of date becomes a binding constraint on the PRD. |
+| "I picked the best option, so listing the alternatives is padding." | Iron Law 3: architecture decisions list the alternatives considered. Without them, the next person to question the decision has to redo the research, and usually re-decides it differently. |
+| "The existing project does this badly, so I'll specify the correct pattern instead." | Iron Law 6: existing patterns win unless they are genuinely antipatterns — and if they are, say so explicitly with the reason. A silent replacement produces a PRD whose constraints contradict the codebase it will be implemented in. |
+| "'Use proper error handling' captures the intent well enough." | Iron Law 5: constraints must be checkable. Phase 5 validates the PRD against these line by line; prose advice passes trivially and constrains nothing. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.cursor.md

@@ -5,6 +5,10 @@ description: >
   application architecture patterns. Produces constraints that PRD must follow.
   Use when: dispatched by gproject-orchestrator Phase 3.
   NOT for: direct user invocation.
+triggers:
+  - "research patterns"
+  - "architecture patterns"
+  - "best practices"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,18 @@ and architectural decisions for each technology. The output becomes a set of
 | 5 | Output MUST be structured as checkable constraints, not prose advice |
 | 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "Clean Architecture is the right answer for any serious project." | Iron Law 2: patterns must fit the chosen level. Layer boundaries and ports-and-adapters on an MVP buy indirection nobody has time to maintain, and Phase 4 is then bound by a constraint that slows every task. |
+| "This is standard practice, so it needs no source." | Iron Law 1: every pattern cites official docs, community consensus, or established practice. Uncited standard practice is how a convention three major versions out of date becomes a binding constraint on the PRD. |
+| "I picked the best option, so listing the alternatives is padding." | Iron Law 3: architecture decisions list the alternatives considered. Without them, the next person to question the decision has to redo the research, and usually re-decides it differently. |
+| "The existing project does this badly, so I'll specify the correct pattern instead." | Iron Law 6: existing patterns win unless they are genuinely antipatterns — and if they are, say so explicitly with the reason. A silent replacement produces a PRD whose constraints contradict the codebase it will be implemented in. |
+| "'Use proper error handling' captures the intent well enough." | Iron Law 5: constraints must be checkable. Phase 5 validates the PRD against these line by line; prose advice passes trivially and constrains nothing. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.md

@@ -5,6 +5,10 @@ description: >
   application architecture patterns. Produces constraints that PRD must follow.
   Use when: dispatched by gproject-orchestrator Phase 3.
   NOT for: direct user invocation.
+triggers:
+  - "research patterns"
+  - "architecture patterns"
+  - "best practices"
 metadata:
   version: 1.0.0
 ---
@@ -28,6 +32,18 @@ and architectural decisions for each technology. The output becomes a set of
 | 5 | Output MUST be structured as checkable constraints, not prose advice |
 | 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "Clean Architecture is the right answer for any serious project." | Iron Law 2: patterns must fit the chosen level. Layer boundaries and ports-and-adapters on an MVP buy indirection nobody has time to maintain, and Phase 4 is then bound by a constraint that slows every task. |
+| "This is standard practice, so it needs no source." | Iron Law 1: every pattern cites official docs, community consensus, or established practice. Uncited standard practice is how a convention three major versions out of date becomes a binding constraint on the PRD. |
+| "I picked the best option, so listing the alternatives is padding." | Iron Law 3: architecture decisions list the alternatives considered. Without them, the next person to question the decision has to redo the research, and usually re-decides it differently. |
+| "The existing project does this badly, so I'll specify the correct pattern instead." | Iron Law 6: existing patterns win unless they are genuinely antipatterns — and if they are, say so explicitly with the reason. A silent replacement produces a PRD whose constraints contradict the codebase it will be implemented in. |
+| "'Use proper error handling' captures the intent well enough." | Iron Law 5: constraints must be checkable. Phase 5 validates the PRD against these line by line; prose advice passes trivially and constrains nothing. |
+
 ---
 
 ## Input Contract