@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/codex/harness-pre-commit-review/SKILL.md

@@ -0,0 +1,324 @@
+# Harness Pre-Commit Review
+
+> Lightweight pre-commit quality gate — mechanical checks first, AI review second. Fast feedback before code leaves your machine.
+
+## When to Use
+
+- Before committing code (manual invocation or git pre-commit hook)
+- As a quick sanity check before pushing to a branch
+- When you want fast feedback without a full code review cycle
+- NOT as a replacement for full peer review (use `harness-code-review` for that)
+- NOT for commits that only update documentation or configuration (fast path skips AI review)
+
+## Principle: Deterministic First
+
+This skill follows the Deterministic-vs-LLM Responsibility Split principle. Mechanical checks run first and must pass before any AI review occurs. If a linter or type checker can catch the problem, the LLM should not be the one finding it.
+
+## Process
+
+### Phase 1: Mechanical Checks
+
+Run all deterministic checks against staged changes. These are binary pass/fail — no judgment required.
+
+#### 1. Detect Available Check Commands
+
+```bash
+# Check for project-specific commands
+cat package.json 2>/dev/null | grep -E '"(lint|typecheck|test)"'
+cat Makefile 2>/dev/null | grep -E '^(lint|typecheck|test):'
+```
+
+#### 2. Run Checks in Order
+
+Run whichever of these are available in the project:
+
+```bash
+# Lint (fastest — run first)
+pnpm lint 2>&1 || npm run lint 2>&1 || make lint 2>&1
+
+# Type check
+pnpm typecheck 2>&1 || npx tsc --noEmit 2>&1 || make typecheck 2>&1
+
+# Tests (slowest — run last)
+pnpm test 2>&1 || npm test 2>&1 || make test 2>&1
+```
+
+#### 2b. Harness Health Check
+
+If the project uses harness, run `assess_project` for harness-specific validation:
+
+```json
+assess_project({
+  path: "<project-root>",
+  checks: ["validate", "deps"],
+  mode: "summary"
+})
+```
+
+If `healthy: false`, include harness check failures in the mechanical check report. This replaces manually running `harness validate` and `harness check-deps` as separate commands.
+
+#### 3. Gate Decision
+
+- **Any check fails:** STOP. Report the failure. Do not proceed to AI review. The author must fix mechanical issues first.
+- **All checks pass:** Proceed to Phase 2.
+
+**Output format for failures:**
+
+```
+Pre-Commit Check: FAIL
+
+Mechanical Checks:
+- Lint: FAIL — 3 errors (see output above)
+- Types: PASS
+- Tests: NOT RUN (blocked by lint failure)
+
+Action: Fix lint errors before committing.
+```
+
+### Graph Freshness Check
+
+If a knowledge graph exists at `.harness/graph/` and code files have changed since the last scan, run `harness scan` before proceeding. The AI review phase uses graph-enhanced MCP tools (impact analysis, harness checks) that return stale results with an outdated graph.
+
+If no graph exists, skip this step — the tools fall back to non-graph behavior.
+
+### Impact Preview
+
+After mechanical checks pass, run `harness impact-preview` to surface the blast radius of staged changes. This is informational only — it never blocks the commit.
+
+```bash
+harness impact-preview
+```
+
+Include the output in the report between the mechanical checks section and the AI review section:
+
+```
+Impact Preview (3 staged files)
+  Code:   12 files   (routes/login.ts, middleware/verify.ts, +10)
+  Tests:   3 tests   (auth.test.ts, integration.test.ts, +1)
+  Docs:    2 docs    (auth-guide.md, api-reference.md)
+  Total:  17 affected
+```
+
+If no graph exists, the command prints a nudge message and returns — no action needed. If no files are staged, it says so. Neither case blocks the workflow.
+
+### Phase 2: Classify Changes
+
+Determine whether AI review is needed based on what changed.
+
+```bash
+# Get list of staged files
+git diff --cached --name-only
+
+# Check if only docs/config files changed
+git diff --cached --name-only | grep -v -E '\.(md|yml|yaml|json|toml|ini|cfg|conf|env|env\..*)$' | wc -l
+```
+
+#### Fast Path: Skip AI Review
+
+If ALL staged files match these patterns, skip AI review and approve:
+
+- `*.md` (documentation)
+- `*.yml`, `*.yaml` (configuration)
+- `*.json` (configuration — unless in `src/`)
+- `*.toml`, `*.ini`, `*.cfg` (configuration)
+- `.env*` (environment — but warn about secrets)
+- `LICENSE`, `CODEOWNERS`, `.gitignore`
+
+**Output for fast path:**
+
+```
+Pre-Commit Check: PASS (fast path)
+
+Mechanical Checks:
+- Lint: PASS
+- Types: PASS
+- Tests: PASS (12/12)
+
+AI Review: SKIPPED (docs/config only)
+```
+
+#### Standard Path: Proceed to AI Review
+
+If any staged file contains code changes, proceed to Phase 3.
+
+### Phase 3: Security Scan
+
+Run the built-in security scanner against staged files. This is a mechanical check — no AI judgment involved.
+
+```bash
+# Get list of staged source files
+git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx|js|jsx|go|py)$'
+```
+
+Run `harness check-security --changed-only` on the staged files. Report any findings:
+
+- **Error findings (blocking):** Hardcoded secrets, eval/injection, weak crypto — these block the commit just like lint failures.
+- **Warning/info findings (advisory):** CORS wildcards, HTTP URLs, disabled TLS — reported but do not block.
+
+Include security scan results in the report output:
+
+```
+Security Scan: [PASS/WARN/FAIL] (N errors, N warnings)
+```
+
+If no source files are staged, skip the security scan.
+
+### Phase 4: AI Review (Lightweight)
+
+Perform a focused, lightweight review of staged changes. This is NOT a full code review — it catches obvious issues only.
+
+#### 1. Quick Review via review_changes
+
+Use the `review_changes` MCP tool with `depth: 'quick'` for fast pre-commit analysis:
+
+```json
+review_changes({
+  path: "<project-root>",
+  diff: "<output of git diff --cached>",
+  depth: "quick",
+  mode: "summary"
+})
+```
+
+This runs forbidden pattern checks and size analysis. For the semantic review items below, supplement with manual diff reading.
+
+#### 2. Quick Review Checklist
+
+Review the staged diff for these high-signal issues only:
+
+- **Obvious bugs:** null dereference, infinite loops, off-by-one errors, resource leaks
+- **Security issues:** hardcoded secrets, SQL injection, path traversal, unvalidated input (complements the mechanical scan with semantic analysis — e.g., tracing user input across function boundaries)
+- **Broken imports:** references to files/modules that do not exist
+- **Debug artifacts:** console.log, debugger statements, TODO/FIXME without issue reference
+- **Type mismatches:** function called with wrong argument types (if visible in diff)
+
+Do NOT review for:
+
+- Style (that is the linter's job)
+- Architecture (that is the full review's job)
+- Test completeness (that is the full review's job)
+- Naming preferences (subjective and noisy at this stage)
+
+#### 3. Report
+
+**If no issues found:**
+
+```
+Pre-Commit Check: PASS
+
+Mechanical Checks:
+- Lint: PASS
+- Types: PASS
+- Tests: PASS (12/12)
+- Security Scan: PASS (0 errors, 0 warnings)
+
+Impact Preview (3 staged files)
+  Code:   12 files   (routes/login.ts, middleware/verify.ts, +10)
+  Tests:   3 tests   (auth.test.ts, integration.test.ts, +1)
+  Docs:    2 docs    (auth-guide.md, api-reference.md)
+  Total:  17 affected
+
+AI Review: PASS (no issues found)
+```
+
+**If issues found:**
+
+```
+Pre-Commit Check: WARN
+
+Mechanical Checks:
+- Lint: PASS
+- Types: PASS
+- Tests: PASS (12/12)
+- Security Scan: WARN (0 errors, 1 warning)
+  - [SEC-NET-001] src/cors.ts:5 — CORS wildcard origin
+
+Impact Preview (2 staged files)
+  Code:    8 files   (cors.ts, server.ts, +6)
+  Tests:   2 tests   (cors.test.ts, server.test.ts)
+  Total:  10 affected
+
+AI Review: 2 observations
+1. [file:line] Possible null dereference — `user.email` accessed without null check after `findUser()` which can return null.
+2. [file:line] Debug artifact — `console.log('debug:', payload)` appears to be left from debugging.
+
+Action: Review observations above. Commit anyway if intentional, or fix first.
+```
+
+## Git Hook Installation
+
+To use as an automatic pre-commit hook, add to `.git/hooks/pre-commit` or configure via your git hooks manager (husky, lefthook, etc.):
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+harness skill run harness-pre-commit-review
+exit_code=$?
+if [ $exit_code -ne 0 ]; then
+  echo "Pre-commit review failed. Fix issues before committing."
+  exit 1
+fi
+```
+
+**Note:** AI review observations (WARN) do not block the commit — only mechanical check failures (FAIL) block. The author decides whether to address AI observations.
+
+## Gates
+
+- **Mechanical checks must pass before AI review.** Do not run AI review if lint/typecheck/tests fail.
+- **Fast path is mandatory.** If only docs/config changed, skip AI review — do not waste tokens.
+- **AI review is advisory only.** Observations do not block the commit. Only mechanical failures block.
+
+## Harness Integration
+
+- Follows Principle 7 (Deterministic-vs-LLM Split) — mechanical checks first, AI review second
+- Reads `.harness/review-learnings.md` for calibration (if present)
+- Complements harness-code-review (full review) — use pre-commit for quick checks, code-review for thorough analysis
+- **`assess_project`** — Used in Phase 1 for harness-specific health checks (validate + deps) in a single call.
+- **`review_changes`** — Used in Phase 4 with `depth: 'quick'` for fast pre-commit diff analysis.
+- **`harness impact-preview`** — Run after mechanical checks pass to show blast radius of staged changes. Informational only — never blocks.
+
+## Success Criteria
+
+- [ ] Mechanical checks ran and produced clear pass/fail results
+- [ ] Fast path correctly identified docs/config-only changes
+- [ ] AI review focused on high-signal issues only (no style nits)
+- [ ] Report follows the structured format exactly
+
+## Examples
+
+### Example: Clean Commit
+
+```
+Pre-Commit Check: PASS
+
+Mechanical Checks:
+- Lint: PASS
+- Types: PASS
+- Tests: PASS (12/12)
+
+Impact Preview (2 staged files)
+  Code:    5 files   (auth.ts, login.ts, +3)
+  Tests:   2 tests   (auth.test.ts, login.test.ts)
+  Total:   7 affected
+
+AI Review: PASS (no issues found)
+```
+
+### Example: Docs-Only Fast Path
+
+```
+Pre-Commit Check: PASS (fast path)
+
+Mechanical Checks:
+- Lint: PASS
+- Types: PASS
+- Tests: PASS (12/12)
+
+AI Review: SKIPPED (docs/config only)
+```
+
+## Escalation
+
+- **Mechanical checks fail:** Fix the issues. Do not bypass the hook.
+- **AI review finds a potential issue you disagree with:** Commit anyway — AI review observations are advisory, not blocking. If the observation is consistently wrong, add it to `.harness/review-learnings.md` under Noise / False Positives.
+- **Hook is too slow:** If the full test suite is slow, configure the project to run only affected tests in pre-commit. The full suite runs in CI.

package/dist/agents/skills/codex/harness-pre-commit-review/skill.yaml

@@ -0,0 +1,34 @@
+name: harness-pre-commit-review
+version: "1.0.0"
+description: Lightweight pre-commit quality gate combining mechanical checks and AI review
+triggers: [manual, on_commit]
+platforms: [claude-code, gemini-cli]
+tools: [Bash, Read, Glob, Grep]
+cli:
+  command: harness skill run harness-pre-commit-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-pre-commit-review
+    path: string
+type: rigid
+tier: 3
+phases:
+  - name: mechanical-checks
+    description: Run deterministic checks (lint, typecheck, tests)
+    required: true
+  - name: classify-changes
+    description: Determine if AI review is needed based on change type
+    required: true
+  - name: ai-review
+    description: Lightweight AI review of staged changes (skipped for docs/config-only)
+    required: false
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-code-review

package/dist/agents/skills/codex/harness-product-spec/SKILL.md

@@ -0,0 +1,285 @@
+# Harness Product Spec
+
+> Generate structured product specifications from feature requests, issues, or descriptions. Produces user stories with EARS acceptance criteria, Given-When-Then scenarios, and PRD documents with traceable requirements.
+
+## When to Use
+
+- When a new feature needs formal specification before implementation begins
+- When GitHub issues or feature requests need to be translated into actionable user stories
+- When acceptance criteria are missing, vague, or untestable for existing stories
+- NOT for technical architecture decisions (use harness-architecture-advisor)
+- NOT for implementation planning with task breakdown (use harness-planning)
+- NOT for bug triage or root cause analysis (use harness-debugging)
+
+## Process
+
+### Phase 1: PARSE -- Extract Feature Intent
+
+1. **Resolve input source.** Accept one of:
+   - GitHub issue URL: fetch via `gh issue view <number> --json title,body,labels,comments`
+   - Feature description file: read the provided file path
+   - Inline text: use the provided description directly
+
+2. **Extract core elements.** From the input, identify:
+   - **Goal:** What is the user trying to accomplish?
+   - **Actor(s):** Who are the users or systems involved? (e.g., "admin user," "API consumer," "billing system")
+   - **Trigger:** What initiates the feature? (user action, system event, time-based)
+   - **Constraints:** What limitations exist? (performance, platform, backward compatibility)
+   - **Context:** What existing system components are involved?
+
+3. **Identify ambiguities.** Flag any element that is missing or unclear:
+   - "This issue mentions 'notifications' but does not specify the channel (email, in-app, push)"
+   - "No success metric defined -- what does 'working correctly' mean?"
+   - "Edge case not addressed: what happens when the user has no payment method?"
+
+4. **Resolve ambiguities.** Use `emit_interaction` to present questions when critical information is missing:
+
+   ```
+   The feature request mentions "user notifications" but does not specify:
+   1. Notification channel (email, in-app, push, SMS)
+   2. Whether notifications are configurable by the user
+   3. Retry behavior for failed deliveries
+   Please clarify before proceeding.
+   ```
+
+5. **Load project context.** Scan the project for existing specs, user stories, or PRDs to maintain consistency in format and terminology:
+   - Check `docs/changes/`, `docs/requirements/`, `docs/prd/` for existing documents
+   - Check `.github/ISSUE_TEMPLATE/` for the project's preferred issue format
+   - Identify domain terminology used in existing specs
+
+6. **Classify feature type.** Categorize the feature as:
+   - **New capability:** Something the system cannot do today
+   - **Enhancement:** Improvement to an existing capability
+   - **Integration:** Connecting with an external system
+   - **Migration:** Moving from one approach to another
+
+---
+
+### Phase 2: CRAFT -- Generate User Stories and Acceptance Criteria
+
+1. **Write user stories.** For each actor-goal pair, produce a story in standard format:
+
+   ```
+   As a [actor],
+   I want to [action],
+   so that [benefit].
+   ```
+
+   Break large features into multiple stories. Each story must be independently deliverable and testable.
+
+2. **Write EARS acceptance criteria.** Apply the EARS (Easy Approach to Requirements Syntax) patterns:
+   - **Ubiquitous:** "The [system] shall [behavior]" -- for unconditional requirements
+   - **Event-driven:** "When [trigger], the [system] shall [behavior]" -- for responses to events
+   - **State-driven:** "While [state], the [system] shall [behavior]" -- for ongoing conditions
+   - **Optional:** "Where [feature is enabled], the [system] shall [behavior]" -- for configurable behavior
+   - **Unwanted:** "If [condition], then the [system] shall [response]" -- for error handling and edge cases
+
+3. **Write Given-When-Then scenarios.** For each acceptance criterion, produce at least one BDD scenario:
+
+   ```
+   Given [precondition],
+   When [action],
+   Then [expected outcome].
+   ```
+
+   Include:
+   - Happy path scenario
+   - At least one error/edge case scenario
+   - Boundary condition scenarios where applicable
+
+4. **Define edge cases.** For each story, enumerate:
+   - What happens with empty input?
+   - What happens with maximum input?
+   - What happens when the user lacks permission?
+   - What happens during concurrent access?
+   - What happens when a dependency is unavailable?
+
+5. **Assign story metadata.** For each story:
+   - **Priority:** Must-have, Should-have, Could-have, Won't-have (MoSCoW)
+   - **Size estimate:** S, M, L, XL (relative to other stories)
+   - **Dependencies:** Other stories or systems this depends on
+   - **Risk:** Low, Medium, High (with risk description)
+
+---
+
+### Phase 3: GENERATE -- Produce PRD Document
+
+1. **Structure the PRD.** Generate a document with these sections:
+   - **Title and version** (feature name, PRD version, date, author)
+   - **Problem statement** (what problem does this solve, who has it, how painful is it)
+   - **Goals and non-goals** (explicit scope boundaries)
+   - **User stories** (from Phase 2, organized by priority)
+   - **Acceptance criteria** (EARS format, traceable to stories)
+   - **Technical constraints** (performance requirements, platform constraints, backward compatibility)
+   - **Success metrics** (measurable outcomes that define "done")
+   - **Open questions** (unresolved ambiguities from Phase 1)
+   - **Out of scope** (explicitly excluded items)
+
+2. **Write the problem statement.** Include:
+   - Who is affected (specific user segments)
+   - How the problem manifests today (current workaround or pain)
+   - Quantified impact if available (time lost, error rate, support tickets)
+
+3. **Define success metrics.** Every metric must be:
+   - **Measurable:** Can be tracked with existing or planned instrumentation
+   - **Time-bound:** Has a target timeline for evaluation
+   - **Specific:** Not "improve user experience" but "reduce checkout abandonment by 15% within 30 days"
+
+4. **Map requirements to stories.** Create a traceability matrix:
+
+   ```
+   REQ-001 -> US-001, US-003 (must-have)
+   REQ-002 -> US-002 (should-have)
+   REQ-003 -> US-004, US-005 (could-have)
+   ```
+
+5. **Write the PRD to file.** Save to the project's spec directory (detected in Phase 1 or defaulting to `docs/changes/`). Use a filename pattern: `YYYY-MM-DD-feature-name-prd.md`.
+
+---
+
+### Phase 4: VALIDATE -- Verify Completeness and Testability
+
+1. **Check story independence.** Verify each user story can be delivered independently:
+   - Does the story depend on another story being completed first?
+   - If yes, is the dependency documented?
+   - Can the story be tested in isolation?
+
+2. **Check acceptance criteria testability.** Every EARS criterion must be verifiable:
+   - Can an automated test be written for this criterion?
+   - Is the expected behavior specific enough to distinguish pass from fail?
+   - Are boundary values defined (not "handles large files" but "handles files up to 100MB")?
+     Flag untestable criteria: "Criterion AC-003 says 'the system should be fast' -- this is not testable. Recommend: 'the system shall respond within 200ms for the 95th percentile.'"
+
+3. **Check coverage completeness.** Verify all parsed elements from Phase 1 are addressed:
+   - Every actor has at least one story
+   - Every constraint has a corresponding acceptance criterion
+   - Every ambiguity is either resolved or listed in open questions
+   - Error handling is specified for every user-facing action
+
+4. **Check format consistency.** Verify the output matches existing project conventions:
+   - Story format matches templates in `.github/ISSUE_TEMPLATE/` if present
+   - Terminology matches existing specs (do not introduce "user" when the project uses "member")
+   - Priority scheme matches existing stories
+
+5. **Output validation summary:**
+
+   ```
+   Product Spec Validation: [COMPLETE/INCOMPLETE]
+   Stories: N generated (M must-have, K should-have)
+   Acceptance criteria: N (all testable: YES/NO)
+   BDD scenarios: N (covering N criteria)
+   Coverage: all actors covered, all constraints addressed
+   Open questions: N remaining
+
+   Generated: docs/changes/2026-03-27-notifications-prd.md
+   ```
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-product-spec`** -- Primary command for generating product specifications.
+- **`harness validate`** -- Run after generating specs to verify project health.
+- **`Bash`** -- Used to fetch GitHub issues via `gh` CLI and check existing spec files.
+- **`Read`** -- Used to read input feature descriptions, existing specs, and issue templates.
+- **`Write`** -- Used to generate PRD documents and user story files.
+- **`Glob`** -- Used to locate existing spec directories, issue templates, and requirement documents.
+- **`Grep`** -- Used to extract domain terminology from existing specs and find related stories.
+- **`emit_interaction`** -- Used to present ambiguities for clarification and confirm spec structure before writing.
+
+## Success Criteria
+
+- Every feature input produces at least one user story with EARS acceptance criteria
+- All acceptance criteria are testable (specific, measurable, with defined boundaries)
+- BDD scenarios cover happy path and at least one error/edge case per criterion
+- PRD document includes all required sections with traceable requirements
+- Ambiguities are surfaced and either resolved or tracked as open questions
+- Output format matches existing project conventions when they exist
+- Generated PRD is saved to the correct directory with consistent naming
+
+## Examples
+
+### Example: GitHub Issue to PRD for Team Notifications
+
+```
+Phase 1: PARSE
+  Source: gh issue view 234 (title: "Add team notification preferences")
+  Actor: team admin, team member
+  Goal: control which notifications team members receive
+  Ambiguities found:
+    - Channel not specified (resolved: email + in-app per comment #3)
+    - "Important notifications" undefined (flagged as open question)
+
+Phase 2: CRAFT
+  US-001: As a team admin, I want to set default notification preferences for my team,
+          so that new members receive appropriate notifications without manual setup.
+    AC-001 (Ubiquitous): The system shall apply team-default preferences to new members on join.
+    AC-002 (Event-driven): When a team admin updates default preferences, the system shall
+            prompt whether to apply to existing members.
+    AC-003 (Unwanted): If a team member has custom preferences, then the system shall
+            preserve them when team defaults change.
+
+  US-002: As a team member, I want to override team notification defaults,
+          so that I receive only notifications relevant to my role.
+    Scenario: Given a team member with default preferences,
+              When they disable "deployment" notifications,
+              Then they shall not receive deployment notifications
+              And their other preferences remain unchanged.
+
+Phase 3: GENERATE
+  Written: docs/changes/2026-03-27-team-notifications-prd.md
+  Sections: problem statement, 4 user stories, 12 acceptance criteria, 8 BDD scenarios
+  Traceability: REQ-001 -> US-001, US-002 | REQ-002 -> US-003, US-004
+
+Phase 4: VALIDATE
+  Stories: 4 (2 must-have, 1 should-have, 1 could-have)
+  Acceptance criteria: 12 (all testable: YES)
+  Open questions: 1 ("important notifications" needs product definition)
+  Result: COMPLETE
+```
+
+### Example: Inline Feature Description for Stripe Webhook Integration
+
+```
+Phase 1: PARSE
+  Source: inline text "We need to handle Stripe webhooks for subscription changes"
+  Actor: billing system (automated), finance admin (human oversight)
+  Constraints: idempotency required, webhook signature verification, 5-second response SLA
+  Ambiguities:
+    - Which subscription events? (resolved via clarification: created, updated, canceled, past_due)
+    - Retry handling? (Stripe retries for 72 hours)
+
+Phase 2: CRAFT
+  US-001: As the billing system, I want to process Stripe subscription.updated webhooks,
+          so that user plan changes are reflected within 60 seconds.
+    AC-001 (Event-driven): When a subscription.updated webhook arrives, the system shall
+            update the user's plan within 60 seconds.
+    AC-002 (Unwanted): If a duplicate webhook event ID is received, then the system shall
+            return 200 OK without reprocessing.
+    AC-003 (Unwanted): If webhook signature verification fails, then the system shall
+            return 400 and log a security warning.
+
+Phase 3: GENERATE
+  Written: docs/changes/2026-03-27-stripe-webhooks-prd.md
+  Technical constraints section includes: idempotency keys, signature verification,
+    5-second response SLA, Stripe retry behavior documentation
+
+Phase 4: VALIDATE
+  All 4 webhook event types have stories: YES
+  Idempotency criterion is testable: YES (duplicate event ID -> no side effects)
+  Result: COMPLETE
+```
+
+## Gates
+
+- **No generating specs from ambiguous input without clarification.** If the input lacks a clear actor, goal, or trigger, pause and ask. Do not invent requirements that were not stated or implied.
+- **No untestable acceptance criteria.** Every criterion must be verifiable by an automated test or a specific manual procedure. "The system should be user-friendly" is not an acceptance criterion.
+- **No skipping edge cases for user-facing actions.** Every action that a user can trigger must have at least one unwanted-behavior criterion (EARS "If" pattern) covering the error case.
+- **No overwriting existing specs.** If a PRD already exists for this feature, present the diff rather than replacing the file. Existing specs may have been reviewed and approved.
+
+## Escalation
+
+- **When the feature request is too vague to parse:** Present what was extracted and what is missing: "This issue contains a title but no description. I need at minimum: who is the user, what action they want to perform, and why. Please add details to the issue or provide them here."
+- **When requirements conflict with existing system behavior:** Flag the conflict: "AC-003 requires real-time sync, but the existing event system uses eventual consistency with up to 30-second delay. This needs an architectural decision before the spec can be finalized."
+- **When the feature scope is too large for a single PRD:** Recommend splitting: "This feature contains 3 independent capabilities (notifications, preferences, audit log). Recommend splitting into 3 PRDs that can be prioritized and delivered independently."
+- **When acceptance criteria require metrics that do not exist yet:** Flag the instrumentation gap: "Success metric 'reduce checkout time by 20%' requires checkout timing instrumentation that does not currently exist. Add an instrumentation story as a prerequisite."