@softspark/ai-toolkit 1.3.14 → 1.3.15

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.15 — Quality Guardrails: Anti-Rationalization, Confidence Scoring, Verification Checklists (2026-04-08)
+
+### Added
+- **Anti-rationalization tables** — 15 core skills now include `## Common Rationalizations` sections with domain-specific excuse/rebuttal tables that prevent agent drift and shortcut-taking. Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills).
+- **Confidence scoring** (`/review`) — review findings now include per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit) with a calibration guide.
+- **LLM-as-Judge self-evaluation** (`/review`) — structured self-check after review: blind spot detection, anchoring bias check, and confidence calibration.
+- **Agent verification checklists** — 10 key agents (`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`) now include `## Verification Checklist` exit criteria.
+- **Skill reference routing** — 7 core skills (`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`) include `## Related Skills` sections for follow-up discoverability.
+- **Intent Capture Interview** (`/onboard`) — Step 0 interview phase with 5 targeted questions to capture undocumented project intent before setup.
+
+---
+
 ## v1.3.14 — CVE Scanner + Open Contributions (2026-04-08)
 
 ### Added

package/README.md

@@ -385,6 +385,43 @@ Three skills enforce non-negotiable quality gates with anti-rationalization tabl
 | `debugging-tactics` | `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST` | 4-phase debugging: root cause → pattern → hypothesis → fix. 3+ failed fixes → question architecture. |
 | `verification-before-completion` | `NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE` | Gate function: IDENTIFY → RUN → READ → VERIFY → CLAIM. "Should work now" is not evidence. |
 
+Additionally, **15 core skills** include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift and shortcut-taking. Skills with rationalization tables: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
+
+### Confidence Scoring & Self-Evaluation (`/review`)
+
+The `/review` skill outputs findings with per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit). After completing a review, an LLM-as-Judge self-evaluation pass checks for blind spots: anchoring bias, assumption vs verification, missing unhappy paths, and calibrates confidence scores.
+
+### Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria that MUST be met before presenting results. Each checklist is domain-specific:
+
+| Agent | Key exit criteria |
+|-------|------------------|
+| `code-reviewer` | Every finding has file:line + evidence, not just opinion |
+| `security-auditor` | Each finding includes proof-of-concept or exploit path |
+| `test-engineer` | No empty/placeholder tests, mocks only at boundaries |
+| `debugger` | Root cause identified, regression test added |
+| `backend-specialist` | Input validation, error format, query optimization |
+| `frontend-specialist` | Empty/loading/error states, accessibility, responsive |
+| `database-architect` | Migration tested on prod-like volume, rollback tested |
+| `performance-optimizer` | Baseline measured, profiler evidence attached |
+| `devops-implementer` | Dry run passed, rollback documented, no hardcoded secrets |
+| `documenter` | Code examples runnable, no placeholders, valid links |
+
+### Skill Reference Routing
+
+7 core skills include `## Related Skills` sections that suggest logical follow-up skills, improving discoverability:
+
+```
+/review → found issues? → /debug, /tdd, /cve-scan, /analyze
+/debug  → bug fixed?   → /review, /tdd, /workflow incident-response
+/plan   → approved?    → /orchestrate, /write-a-prd, /grill-me
+```
+
+### Intent Capture Interview (`/onboard`)
+
+The `/onboard` skill now includes a Step 0 interview phase before setup — asking 5 targeted questions to capture undocumented project intent (common contributor mistakes, protected files, deployment model, non-obvious constraints, review culture). Answers customize the generated `CLAUDE.md`.
+
 ### 7. Two-Stage Review (`/subagent-development`)
 
 Per-task review pipeline inspired by [obra/superpowers](https://github.com/obra/superpowers):

package/app/agents/backend-specialist.md

@@ -184,6 +184,14 @@ After implementing significant changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting implementation:
+- [ ] All new endpoints have input validation
+- [ ] Error responses follow the project's error format
+- [ ] Database queries are optimized (checked with EXPLAIN if applicable)
+- [ ] New dependencies are justified and audited
+- [ ] Migration is reversible
+
 ## KB Integration
 
 Before coding, search knowledge base:

package/app/agents/code-reviewer.md

@@ -177,6 +177,15 @@ After significant reviews, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting review results:
+- [ ] Every finding includes file:line reference
+- [ ] Each finding has evidence (code snippet or reasoning), not just opinion
+- [ ] Severity rating reflects actual impact, not gut feeling
+- [ ] "No findings" includes list of specific checks performed
+- [ ] Security-sensitive files received deeper scrutiny
+- [ ] Test coverage gaps are flagged, not assumed covered
+
 ## Limitations
 
 - **Security penetration testing** → Use `security-auditor`

package/app/agents/database-architect.md

@@ -308,6 +308,14 @@ After schema/database changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting schema changes:
+- [ ] Migration tested on production-like data volume
+- [ ] Rollback script exists and was tested
+- [ ] Indexes cover the expected query patterns
+- [ ] No long-running locks on large tables
+- [ ] Application handles both old and new schema during migration
+
 ## KB Integration
 
 Before designing, search knowledge base:

package/app/agents/debugger.md

@@ -231,6 +231,14 @@ After fixing significant bugs, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before claiming a bug is fixed:
+- [ ] Root cause identified, not just symptoms addressed
+- [ ] Fix was verified by reproducing the original failure first
+- [ ] Regression test added to prevent recurrence
+- [ ] Related code paths checked for similar issues
+- [ ] Fix doesn't introduce new side effects
+
 ## Limitations
 
 - **Performance profiling** → Use `performance-optimizer`

package/app/agents/devops-implementer.md

@@ -187,6 +187,14 @@ instructions: |
 ---
 ```
 
+## Verification Checklist
+Before presenting infrastructure changes:
+- [ ] Dry run completed successfully
+- [ ] Rollback procedure documented and tested
+- [ ] Secrets are not hardcoded or logged
+- [ ] Health checks configured for new services
+- [ ] Resource limits set to prevent runaway costs
+
 ## Limitations
 
 - **Architectural decisions** → Use `infrastructure-architect`

package/app/agents/documenter.md

@@ -357,6 +357,14 @@ last_updated: "YYYY-MM-DD"
 - Add diagrams where helpful
 - Version documentation with code
 
+## Verification Checklist
+Before presenting documentation:
+- [ ] Code examples are tested and runnable
+- [ ] No placeholder text or TODO markers remain
+- [ ] Links and references are valid
+- [ ] Architecture decisions include rationale (not just "what")
+- [ ] KB documents have complete YAML frontmatter
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/agents/frontend-specialist.md

@@ -200,6 +200,14 @@ After implementing significant changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting implementation:
+- [ ] Components render correctly with empty/loading/error states
+- [ ] Accessibility basics checked (keyboard nav, aria labels, contrast)
+- [ ] No console errors or warnings in dev tools
+- [ ] Responsive behavior verified at mobile/tablet/desktop breakpoints
+- [ ] Bundle size impact assessed for new dependencies
+
 ## KB Integration
 
 Before coding, search knowledge base:

package/app/agents/performance-optimizer.md

@@ -247,6 +247,14 @@ After performance optimizations, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting optimization:
+- [ ] Baseline measurement taken before changes
+- [ ] Improvement measured with realistic data, not synthetic benchmarks
+- [ ] No regressions in other metrics (memory, latency, correctness)
+- [ ] Optimization targets the actual bottleneck (profiler evidence attached)
+- [ ] Cache invalidation strategy documented if caching was added
+
 ## Limitations
 
 - **Production incidents** → Use `incident-responder`

package/app/agents/security-auditor.md

@@ -301,6 +301,15 @@ For large documentation tasks, hand off to `documenter` agent.
 - No destructive testing without explicit approval
 - Report findings responsibly
 
+## Verification Checklist
+Before presenting security findings:
+- [ ] Each finding includes proof-of-concept or exploit path
+- [ ] Severity ratings reference actual impact, not theoretical risk
+- [ ] "No findings" includes the specific checks performed
+- [ ] Dependencies were scanned, not just application code
+- [ ] Secrets scan covered all file types (not just source code)
+- [ ] Auth flows were traced end-to-end, not spot-checked
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/agents/test-engineer.md

@@ -257,6 +257,15 @@ After writing significant tests, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting test results:
+- [ ] Every test has a clear assertion (no empty or placeholder tests)
+- [ ] Edge cases are explicitly tested, not assumed
+- [ ] Mocks are only at system boundaries, not internal collaborators
+- [ ] Test names describe behavior, not implementation
+- [ ] Flaky test patterns (time, network, order-dependent) are flagged
+- [ ] Coverage gaps are reported with specific uncovered paths
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/skills/analyze/SKILL.md

@@ -82,6 +82,15 @@ python3 ${CLAUDE_SKILL_DIR}/scripts/complexity.py .
 
 Reports file counts by type, largest files, TODO/FIXME counts, and total code lines.
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "The linter is green, the code is fine" | Linters catch syntax, not design flaws — analysis covers architecture and patterns |
+| "We know where the problems are" | Intuition misses systemic issues — data-driven analysis reveals hidden hotspots |
+| "Analysis takes too long" | A 5-minute scan prevents weeks of debugging — front-load the investment |
+| "It's legacy code, analysis won't help" | Legacy code benefits most — find the critical paths before they break |
+
 ## Tools Used
 
 | Language | Tools |
@@ -90,3 +99,9 @@ Reports file counts by type, largest files, TODO/FIXME counts, and total code li
 | JavaScript | eslint, tsc |
 | Go | golangci-lint |
 | Rust | clippy |
+
+## Related Skills
+- Found quality issues? → `/refactor` to fix them systematically
+- Security issues detected? → `/cve-scan` for dependency audit
+- Want deeper architecture review? → `/architecture-audit` for friction discovery
+- Performance hotspots found? → `/workflow performance-optimization`

package/app/skills/api-patterns/SKILL.md

@@ -292,6 +292,16 @@ Accept: application/vnd.myapi.v1+json
 
 ---
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We'll version the API later" | Unversioned APIs break clients on every change — version from day one |
+| "Retries are the client's problem" | Server-side idempotency prevents data corruption — design for at-least-once delivery |
+| "We'll add rate limiting later" | Unprotected endpoints get abused within hours of deployment |
+| "Error messages are just for debugging" | Error responses are your API's UX — clients depend on consistent, parseable errors |
+| "PATCH and PUT are the same thing" | PUT replaces the resource, PATCH modifies it — wrong semantics cause data loss |
+
 ## Best Practices
 
 - [ ] Use HTTPS only

package/app/skills/ci-cd-patterns/SKILL.md

@@ -291,6 +291,16 @@ env:
 | `feat:` | Minor (0.x.0) | `feat: add user search endpoint` |
 | `feat!:` / `BREAKING CHANGE:` | Major (x.0.0) | `feat!: change API response format` |
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "CI is green, ship it" | CI tests the happy path — verify edge cases, security, and performance separately |
+| "Manual deploys give us more control" | Manual deploys give you more human error — automate the repeatable parts |
+| "We'll set up CI when the project is bigger" | Small projects grow fast — CI debt compounds and retrofitting is painful |
+| "Caching isn't worth the complexity" | Uncached builds waste developer time daily — caching pays for itself in a week |
+| "Feature flags are over-engineering" | Feature flags decouple deploy from release — they're the cheapest safety net |
+
 ## Anti-Patterns
 - Secrets in pipeline logs or environment dumps
 - No caching (slow builds)

package/app/skills/clean-code/SKILL.md

@@ -100,6 +100,16 @@ Keep modules focused. Order contents consistently: imports (stdlib, third-party,
 
 ---
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It's readable enough" | "Enough" means someone will misread it eventually — clarity prevents incidents |
+| "Refactoring for readability is gold-plating" | Readability is maintainability — future you will thank present you |
+| "Short variable names are faster to type" | You type it once, readers parse it hundreds of times — optimize for reading |
+| "DRY means never repeat anything" | Wrong DRY creates coupling — duplicate until you see the real abstraction |
+| "More abstractions = cleaner code" | Premature abstraction is worse than duplication — wait for the third use |
+
 ## Language-Specific References
 
 For detailed patterns, type hints, linting configuration, and idiomatic code per language:

package/app/skills/database-patterns/SKILL.md

@@ -296,3 +296,13 @@ client.create_payload_index(
 | COSINE | Text embeddings | Yes |
 | EUCLID | Image embeddings | No |
 | DOT | When vectors pre-normalized | Yes |
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We'll add indexes later when it's slow" | Missing indexes on production tables cause outages, not slowdowns — index from design |
+| "The ORM handles performance" | ORMs generate queries, they don't optimize them — always check the query plan |
+| "NoSQL is faster" | NoSQL trades consistency for speed — if you need joins, use a relational DB |
+| "We don't need migrations, we'll update the schema directly" | Direct schema changes are irreversible and untestable — migrations are the safety net |
+| "One big table is simpler" | Denormalization without measurement creates update anomalies — normalize first, denormalize with data |

package/app/skills/debug/SKILL.md

@@ -144,6 +144,16 @@ Have them talk to each other to challenge each other's theories.
 Report consensus when done.
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works on my machine" | Environment differences are the #1 cause of production bugs — reproduce in prod-like env |
+| "It must be a library bug" | 95% of the time it's your code — exhaust local hypotheses first |
+| "I'll just add more logging and wait" | Passive debugging wastes hours — form a hypothesis and test it actively |
+| "The error message says X, so it must be X" | Error messages often describe symptoms, not root causes — trace the full chain |
+| "It only happens sometimes, probably a fluke" | Intermittent bugs are race conditions or state leaks — they get worse, not better |
+
 ## Debug Checklist
 
 - [ ] Identified error/symptom
@@ -152,3 +162,9 @@ Report consensus when done.
 - [ ] Reproduced issue
 - [ ] Formed hypothesis
 - [ ] Tested fix
+
+## Related Skills
+- Bug fixed? → `/review` to verify the fix quality
+- Need a regression test? → `/tdd` to write it test-first
+- Performance issue? → `/analyze --type=complexity` for hotspot analysis
+- Incident in production? → `/workflow incident-response` for full response

package/app/skills/docs/SKILL.md

@@ -113,6 +113,16 @@ Proposed
 - [ ] Commit changes
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "The code is self-documenting" | Code shows how, not why — decisions, constraints, and context need prose |
+| "Nobody reads docs anyway" | People don't read bad docs — good docs are the first thing consulted |
+| "I'll document it when it's stable" | Unstable code needs docs most — document intent so others can contribute |
+| "Comments get stale" | That's an argument for maintaining docs, not skipping them |
+| "The tests are the documentation" | Tests verify behavior but don't explain architecture, trade-offs, or setup |
+
 ## Configuration
 
 Documentation settings in:
@@ -143,3 +153,9 @@ Create an agent team for documentation:
 - Teammate 3 (documenter): "Generate README sections: installation, usage, API reference." Use Opus.
 Teammates should NOT overlap — each owns their assigned scope.
 ```
+
+## Related Skills
+- Documenting an architecture decision? → `/council` for multi-perspective analysis first
+- Need to explore the codebase? → `/explore` to understand structure before documenting
+- Writing a PRD? → `/write-a-prd` for structured product requirements
+- Auditing existing docs? → `/analyze` for coverage gaps

package/app/skills/git-mastery/SKILL.md

@@ -68,3 +68,13 @@ git cherry-pick --continue
 - `perf:` Performance improvement
 - `test:` Adding missing tests
 - `chore:` Build process/auxiliary tools
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "I'll clean up commits later" | Later means never — write clean commits as you go |
+| "Force push is fine on my branch" | Others may have fetched your branch — use --force-with-lease |
+| "One big commit is simpler" | Big commits are impossible to review, bisect, or revert — keep them atomic |
+| "Merge conflicts mean someone else's problem" | Conflicts mean you diverged too long — rebase frequently to stay aligned |
+| "Commit messages don't matter" | Messages are documentation — future you needs to understand why, not just what |

package/app/skills/onboard/SKILL.md

@@ -17,6 +17,21 @@ Guide the user through setting up the ai-toolkit in their project, including con
 
 ## Setup Steps
 
+### Step 0: Intent Capture Interview
+
+Before setting up tooling, understand the project's undocumented context. Ask the developer these questions (adapt based on what the codebase scan reveals):
+
+1. **What's the one thing a new contributor always gets wrong?** — This reveals the biggest documentation gap
+2. **Are there files or directories that should NOT be modified?** — Identifies protected areas (legacy, generated, vendor)
+3. **What's the deployment model?** — Monolith, microservices, serverless, edge — shapes which agents and skills are most relevant
+4. **Are there non-obvious constraints?** — Compliance requirements, performance budgets, browser support matrix
+5. **What's the team's review culture?** — Strict PR reviews, trunk-based, pair programming — configures `/review` behavior
+
+Use answers to:
+- Customize the generated `CLAUDE.md` with project-specific warnings and conventions
+- Select the right `--profile` (minimal/standard/strict) automatically
+- Pre-configure relevant language rules
+
 ### Step 1: Prerequisites Check
 - [ ] Claude Code CLI installed
 - [ ] ai-toolkit repository cloned

package/app/skills/performance-profiling/SKILL.md

@@ -57,3 +57,13 @@ Always measure -> change -> measure.
 2. **Algorithm**: (O(n²) -> O(n log n))
 3. **Memory**: (Allocation churn, GC pressure)
 4. **Micro-optimization**: (Loop unrolling, etc.) - *Smallest Gains*
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It feels slow, let me optimize this function" | Feelings aren't data — profile first, then optimize the actual bottleneck |
+| "We should optimize everything" | Premature optimization is the root of all evil — focus on the critical path |
+| "Caching will fix it" | Caching masks problems and adds complexity — fix the root cause first |
+| "It's fast enough in dev" | Dev has 1 user — production has thousands and cold caches |
+| "We'll optimize later" | Performance debt compounds — a 100ms regression per sprint = 5s in a year |

package/app/skills/plan/SKILL.md

@@ -95,6 +95,16 @@ During planning:
 - NO code writing
 - NO file creation (except plan)
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We already know what to build" | Assumed requirements lead to rework — validate assumptions explicitly |
+| "Planning is wasted time, just start coding" | Unplanned work has 3-5x more rework — 30 min planning saves days |
+| "The requirements will change anyway" | Plans adapt — without one, you can't assess impact of changes |
+| "It's a small feature, no plan needed" | Small features in complex systems have hidden dependencies — map them |
+| "We'll figure it out as we go" | Discovery without structure leads to scope creep and missed edge cases |
+
 ## Next Steps
 
 After plan approval:
@@ -108,3 +118,9 @@ Before planning:
 smart_query("project template: {type}")
 hybrid_search_kb("architecture {pattern}")
 ```
+
+## Related Skills
+- Plan approved? → `/orchestrate` or `/workflow` to execute with agents
+- Need requirements first? → `/write-a-prd` for structured product requirements
+- Want to stress-test the plan? → `/grill-me` for Socratic questioning
+- Ready to break into issues? → `/prd-to-plan` → `/triage-issue`

package/app/skills/refactor/SKILL.md

@@ -81,6 +81,16 @@ Before executing:
 - [ ] Tests passing
 - [ ] Backup created
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works, don't touch it" | Working code that's hard to maintain slows every future change |
+| "We'll refactor it later" | Later never comes — refactor when the pain is fresh and context is loaded |
+| "It's too risky to change" | That's exactly why it needs refactoring — risk compounds with complexity |
+| "Just one more hack won't hurt" | Each hack makes the next one easier to justify — break the cycle now |
+| "We need to rewrite from scratch" | Incremental refactoring is safer and delivers value continuously |
+
 ## READ BEFORE WRITE
 
 This command analyzes and plans first.
@@ -122,3 +132,9 @@ Create an agent team for refactoring:
 - Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
 Teammate 1 completes first, then Teammate 2 acts on the plan.
 ```
+
+## Related Skills
+- Need a safe refactor plan? → `/refactor-plan` for incremental steps as GitHub RFC
+- Want to validate architecture? → `/analyze` for code quality metrics
+- Need tests before refactoring? → `/tdd` to build safety net first
+- Architecture decision needed? → `/council` for multi-perspective evaluation

package/app/skills/review/SKILL.md

@@ -117,17 +117,40 @@ After all reviewers complete:
 - **Lines Added**: [+count]
 - **Lines Removed**: [-count]
 - **Issues Found**: [count]
+- **Overall Confidence**: [1-10] — how confident the reviewer is in the assessment
 
 ### Findings
 
 #### Critical
 - **[file:line]**: [issue]
-  - [explanation]
+  - Severity: critical | Confidence: [1-10]
+  - Evidence: [specific code reference and reasoning]
   - Suggested fix: [code]
 
-#### Suggestions
+#### Major
+- **[file:line]**: [issue]
+  - Severity: major | Confidence: [1-10]
+  - Evidence: [specific code reference and reasoning]
+  - Suggested fix: [code]
+
+#### Minor
+- **[file:line]**: [issue]
+  - Severity: minor | Confidence: [1-10]
+  - Evidence: [line number + reasoning]
+
+#### Nit
 - **[file:line]**: [suggestion]
-  - [explanation]
+  - Severity: nit | Confidence: [1-10]
+
+### Confidence Guide
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Certain — verified via code, tests, or documentation |
+| 7-8 | High — strong evidence, minor assumptions |
+| 5-6 | Medium — plausible issue, needs author confirmation |
+| 3-4 | Low — speculative, based on patterns not proof |
+| 1-2 | Guess — flag for discussion, don't block on this |
 
 ### Positive Notes
 - [What's good about the code]
@@ -136,6 +159,38 @@ After all reviewers complete:
 [APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "Small change, quick scan is enough" | Small changes introduce subtle bugs — apply consistent review regardless of size |
+| "Tests pass, so the code is correct" | Tests validate specific scenarios, not all behaviors — verify missing coverage |
+| "It's just a refactor, no need for deep review" | Refactors change invariants — verify behavior preservation, not just compilation |
+| "The author is senior, they know what they're doing" | Seniority doesn't prevent mistakes — review the code, not the person |
+| "We're in a hurry, ship it" | Rushed reviews create tech debt that costs 10x more to fix later |
+
+## Self-Evaluation (LLM-as-Judge)
+
+After completing the review, perform a self-evaluation pass:
+
+### Check for Blind Spots
+1. **Did I verify, or assume?** — For each finding, confirm you read the actual code (not inferred from context)
+2. **Did I miss the inverse?** — If you flagged X as a problem, did you check if NOT doing X is also a problem elsewhere?
+3. **Did I anchor on the first issue?** — Review whether early findings biased you toward similar patterns, missing different issue classes
+4. **Did I check the unhappy path?** — Error handling, edge cases, failure modes — not just the golden path
+5. **Did I flag uncertainty?** — Findings with confidence < 6 should be clearly marked as "needs author input"
+
+### Calibrate Confidence
+- If all findings are confidence 7+, you may be overconfident — re-examine the weakest finding
+- If any finding lacks a file:line reference, downgrade it or remove it
+- If you found zero issues, state what you specifically checked (not "looks good")
+
 ## READ-ONLY
 
 This skill only analyzes. It does NOT modify any files.
+
+## Related Skills
+- Issues found? → `/debug` to trace root causes
+- Missing tests? → `/tdd` to add test-first coverage
+- Security findings? → `/cve-scan` for dependency vulnerabilities
+- Architecture concerns? → `/analyze` for deeper code quality metrics

package/app/skills/security-patterns/SKILL.md

@@ -81,6 +81,16 @@ async def resource():
 
 ---
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It's an internal API, security doesn't matter" | Internal APIs get exposed — lateral movement is attackers' primary technique |
+| "The framework handles security" | Frameworks provide tools, not guarantees — misconfiguration is OWASP #5 |
+| "We'll add auth later" | Unauthenticated endpoints in production get discovered within hours |
+| "Nobody would exploit this" | Automated scanners don't care about your threat model — they scan everything |
+| "It's behind a VPN" | VPNs are perimeter defense — zero trust assumes breach already happened |
+
 ## Reference Guides
 
 For authentication patterns (JWT, passwords, token strategy), see [reference/authentication.md](reference/authentication.md).

package/app/skills/tdd/SKILL.md

@@ -172,3 +172,9 @@ Before marking work complete:
 - [ ] Edge cases and errors covered
 
 Can't check all boxes? You skipped TDD. Start over.
+
+## Related Skills
+- Feature complete? → `/review` to get a code review
+- Need to plan the feature first? → `/plan` for task breakdown
+- Want a full test coverage sweep? → `/workflow test-coverage`
+- Debugging a test failure? → `/debug` for systematic root cause analysis

package/app/skills/testing-patterns/SKILL.md

@@ -72,3 +72,13 @@ For PHP PHPUnit patterns, see [reference/php-phpunit.md](reference/php-phpunit.m
 For Go testing patterns, see [reference/go-testing.md](reference/go-testing.md).
 
 For Flutter/Dart testing patterns, see [reference/flutter-testing.md](reference/flutter-testing.md).
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It's too simple to test" | Simple code breaks in integration — test the contract, not the complexity |
+| "Tests slow down development" | Tests slow down bugs reaching production — that's the point |
+| "We'll add tests later" | Untested code accumulates — later means never, and coverage gaps compound |
+| "Mocking everything is fine" | Over-mocking tests the mocks, not the code — mock at boundaries only |
+| "100% coverage means no bugs" | Coverage measures execution, not correctness — focus on behavior assertions |

package/kb/reference/architecture-overview.md

@@ -3,7 +3,7 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.3.14"
+version: "1.3.15"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
@@ -178,6 +178,23 @@ Skills that spawn real parallel agents use:
 
 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+15 core skills include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift. Skills: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
+
+### Confidence Scoring & LLM-as-Judge (`/review`)
+Review findings include per-issue confidence scores (1-10) and severity tiers (critical/major/minor/nit). A self-evaluation pass after review checks for anchoring bias, assumption vs verification, and calibrates confidence.
+
+### Agent Verification Checklists
+10 agents have `## Verification Checklist` — domain-specific exit criteria: `code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+7 core skills include `## Related Skills` suggesting follow-up skills: `/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+Step 0 interview — 5 questions to capture undocumented project intent before setup.
+
 ## Component Relationships
 
 ```

package/kb/reference/skills-catalog.md

@@ -3,7 +3,7 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.3.14"
+version: "1.3.15"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
@@ -171,6 +171,62 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 |-------|-----------|--------|
 | **hive-mind** | `skills/hive-mind/` | Multi-agent aggregation, consensus, swarm patterns |
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+
+15 core skills include `## Common Rationalizations` — domain-specific tables of excuses and rebuttals that prevent agent drift and shortcut-taking:
+
+| Skill | Example rationalization blocked |
+|-------|---------------------------------|
+| `/review` | "Small change, quick scan is enough" |
+| `/debug` | "It must be a library bug" |
+| `/refactor` | "It works, don't touch it" |
+| `/tdd` | "Too simple to test" |
+| `/plan` | "Planning is wasted time, just start coding" |
+| `/docs` | "The code is self-documenting" |
+| `/analyze` | "The linter is green, the code is fine" |
+| `security-patterns` | "It's an internal API, security doesn't matter" |
+| `testing-patterns` | "Tests slow down development" |
+| `api-patterns` | "We'll version the API later" |
+| `ci-cd-patterns` | "Manual deploys give us more control" |
+| `clean-code` | "It's readable enough" |
+| `performance-profiling` | "It feels slow, let me optimize this function" |
+| `git-mastery` | "One big commit is simpler" |
+| `database-patterns` | "We'll add indexes later when it's slow" |
+
+### Confidence Scoring (`/review`)
+
+The `/review` skill outputs structured findings with:
+- **Severity**: critical / major / minor / nit
+- **Confidence score**: 1-10 per finding with calibration guide
+- **Evidence requirement**: each finding must include file:line + reasoning
+
+### Self-Evaluation — LLM-as-Judge (`/review`)
+
+After completing a review, the agent performs a self-evaluation pass:
+1. Verify vs assume — did I read actual code for each finding?
+2. Check the inverse — if X is a problem, is NOT-X also a problem elsewhere?
+3. Detect anchoring bias — did early findings bias toward similar patterns?
+4. Check unhappy paths — error handling, edge cases, failure modes
+5. Calibrate confidence — overconfident? re-examine weakest finding
+
+### Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria before presenting results:
+`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+
+7 core skills include `## Related Skills` sections suggesting logical follow-up skills:
+`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+
+Step 0 interview before setup — 5 targeted questions to capture undocumented project intent, customizing the generated `CLAUDE.md`.
+
+---
+
 ## Advanced Features
 
 ### Effort Levels

package/llms-full.txt

@@ -934,7 +934,7 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.3.14"
+version: "1.3.15"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
@@ -1109,6 +1109,23 @@ Skills that spawn real parallel agents use:
 
 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+15 core skills include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift. Skills: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
+
+### Confidence Scoring & LLM-as-Judge (`/review`)
+Review findings include per-issue confidence scores (1-10) and severity tiers (critical/major/minor/nit). A self-evaluation pass after review checks for anchoring bias, assumption vs verification, and calibrates confidence.
+
+### Agent Verification Checklists
+10 agents have `## Verification Checklist` — domain-specific exit criteria: `code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+7 core skills include `## Related Skills` suggesting follow-up skills: `/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+Step 0 interview — 5 questions to capture undocumented project intent before setup.
+
 ## Component Relationships
 
 ```
@@ -4095,7 +4112,7 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.3.14"
+version: "1.3.15"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
@@ -4263,6 +4280,62 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 |-------|-----------|--------|
 | **hive-mind** | `skills/hive-mind/` | Multi-agent aggregation, consensus, swarm patterns |
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+
+15 core skills include `## Common Rationalizations` — domain-specific tables of excuses and rebuttals that prevent agent drift and shortcut-taking:
+
+| Skill | Example rationalization blocked |
+|-------|---------------------------------|
+| `/review` | "Small change, quick scan is enough" |
+| `/debug` | "It must be a library bug" |
+| `/refactor` | "It works, don't touch it" |
+| `/tdd` | "Too simple to test" |
+| `/plan` | "Planning is wasted time, just start coding" |
+| `/docs` | "The code is self-documenting" |
+| `/analyze` | "The linter is green, the code is fine" |
+| `security-patterns` | "It's an internal API, security doesn't matter" |
+| `testing-patterns` | "Tests slow down development" |
+| `api-patterns` | "We'll version the API later" |
+| `ci-cd-patterns` | "Manual deploys give us more control" |
+| `clean-code` | "It's readable enough" |
+| `performance-profiling` | "It feels slow, let me optimize this function" |
+| `git-mastery` | "One big commit is simpler" |
+| `database-patterns` | "We'll add indexes later when it's slow" |
+
+### Confidence Scoring (`/review`)
+
+The `/review` skill outputs structured findings with:
+- **Severity**: critical / major / minor / nit
+- **Confidence score**: 1-10 per finding with calibration guide
+- **Evidence requirement**: each finding must include file:line + reasoning
+
+### Self-Evaluation — LLM-as-Judge (`/review`)
+
+After completing a review, the agent performs a self-evaluation pass:
+1. Verify vs assume — did I read actual code for each finding?
+2. Check the inverse — if X is a problem, is NOT-X also a problem elsewhere?
+3. Detect anchoring bias — did early findings bias toward similar patterns?
+4. Check unhappy paths — error handling, edge cases, failure modes
+5. Calibrate confidence — overconfident? re-examine weakest finding
+
+### Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria before presenting results:
+`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+
+7 core skills include `## Related Skills` sections suggesting logical follow-up skills:
+`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+
+Step 0 interview before setup — 5 targeted questions to capture undocumented project intent, customizing the generated `CLAUDE.md`.
+
+---
+
 ## Advanced Features
 
 ### Effort Levels

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.14",
+  "version": "1.3.15",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "1.3.14",
+  "version": "1.3.15",
   "description": "Professional-grade AI coding toolkit: 91 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",