prompt_best_practices:
  description: "Review prompt/instruction markdown files for Anthropic prompt engineering best practices."
  match:
    # Add any known prompt files to the include list
    include:
      - "**/CLAUDE.md"
      - "**/AGENTS.md"
      - ".claude/**/*.md"
      - ".deepwork/review/*.md"
      - ".deepwork/jobs/**/*.md"
      - "plugins/**/skills/**/*.md"
      - "learning_agents/skills/**/*.md"   # learning_agents plugin skills are prompt-heavy
      - "learning_agents/agents/**/*.md"   # agent persona definitions
      - "platform/**/*.md"
      - "src/deepwork/standard_jobs/**/*.md"
      - "library/jobs/**/*.md"  # library job step instructions are prompt-heavy files
      - "library/jobs/*/job.yml"          # inline step instructions in job.yml are prompt-heavy
      - "src/deepwork/standard_jobs/*/job.yml"  # standard job inline instructions
      - "**/.deepreview"       # .deepreview files contain inline agent instructions — prompt-heavy content
  review:
    strategy: individual
    instructions:
      file: .deepwork/review/prompt_best_practices.md

python_code_review:
  description: "Review Python files against project conventions and best practices."
  match:
    include:
      - "**/*.py"
    exclude:
      - "tests/fixtures/**"
  review:
    strategy: individual
    instructions: |
      Review this Python file against the project's coding conventions
      documented in doc/code_review_standards.md and the ruff/mypy config
      in pyproject.toml.

      Check for:
      - Adherence to project naming conventions (snake_case for functions/variables,
        PascalCase for classes)
      - Proper error handling following project patterns
      - Import ordering (stdlib, third-party, local — enforced by ruff isort)
      - Type hints on function signatures (enforced by mypy disallow_untyped_defs)
      - Security concerns (injection, unsafe deserialization, path traversal)
      - Performance issues (unnecessary computation, resource leaks)

      Additionally, always check:
      - **DRY violations**: Is there duplicated logic or repeated patterns that
        should be extracted into a shared function, utility, or module? Look for
        copy-pasted code with minor variations and similar code blocks differing
        only in variable names.
      - **Comment accuracy**: Are all comments, docstrings, and inline
        documentation still accurate after the changes? Flag any comments that
        describe behavior that no longer matches the code.

      Output Format:
      - PASS: No issues found.
      - FAIL: Issues found. List each with file, line, severity (high/medium/low),
        and a concise description.

python_lint:
  description: "Auto-fix lint and format issues, then report anything unresolvable."
  match:
    include:
      - "**/*.py"
    exclude:
      - "tests/fixtures/**"
  review:
    strategy: matches_together
    instructions: |
      This is an auto-fix rule — you SHOULD edit files to resolve issues.

      Run ruff and mypy on the changed Python files listed below. Fix what you
      can automatically, then report only issues that remain unresolved.

      Steps:
      1. Run `uv run ruff check --fix` on all listed files.
      2. Run `uv run ruff format` on all listed files.
      3. Run `uv run mypy` on all listed files.
      4. Fix any remaining issues you can resolve (e.g., adding type annotations,
         renaming ambiguous variables).
      5. Re-run all three checks to confirm your fixes are clean.

      Output Format:
      - PASS: All checks pass (no remaining issues).
      - FAIL: Unfixable lint errors, type errors, DRY violations, or stale
        comments remain. List each with file, line, and details.

suggest_new_reviews:
  description: "Analyze all changes and suggest new review rules that would catch issues going forward."
  match:
    include:
      - "**/*"
    exclude:
      - ".github/**"
  review:
    strategy: matches_together
    instructions:
      file: .deepwork/review/suggest_new_reviews.md

requirements_traceability:
  description: "Verify requirements traceability between specs, code, tests, review rules, and DeepSchemas."
  match:
    include:
      - "**/*"
    exclude:
      - ".github/**"
  review:
    strategy: all_changed_files
    agent:
      claude: requirements-reviewer
    instructions: |
      Review the changed files for requirements traceability.

      This project keeps formal requirements in `specs/` organized by domain.
      Each file follows the naming pattern `{PREFIX}-REQ-NNN-<topic>.md` where
      PREFIX is one of: DW-REQ, JOBS-REQ, REVIEW-REQ, LA-REQ, PLUG-REQ.
      Requirements are individually numbered (e.g. JOBS-REQ-004.1). Requirements
      must be validated by either automated tests OR DeepWork review rules.

      ## Choosing the right validation mechanism

      Choosing the right mechanism is critical. The wrong choice creates
      false confidence (a passing test that doesn't actually verify anything)
      or wastes reviewer judgment on something a machine can check exactly.

      **Use automated tests** (`tests/`) when the requirement specifies a
      concrete, machine-verifiable fact:
      - File exists at a specific path
      - JSON/YAML field has a specific value
      - Config contains a specific identifier (e.g., `mcp__deepwork__get_review_instructions`)
      - File A is byte-identical to file B
      - A data structure has a required shape

      Tests reference requirement IDs via docstrings and traceability comments.

      **Use `.deepreview` rules** when evaluating the requirement requires
      judgment AND applies broadly across many files of a type:
      - "All prompts MUST use the terms X, Y, and Z" — a general standard
        that applies to every file matching a glob pattern
      - "Code MUST follow pattern Y" — does the implementation match the
        spirit of the pattern across multiple files?
      - "Documentation MUST stay in sync with code" — are the descriptions
        still accurate after changes?

      **Use anonymous DeepSchemas** (`.deepschema.<filename>.yml`) when the
      requirement is specific to a single file's behavior or content:
      - "The error message in situation X MUST include a suggestion for how
        to fix the problem" — place the requirement in a `.deepschema` for
        the file that implements that functionality
      - "This config file MUST include a timeout field" — a structural
        requirement for one specific file
      - "Skill MUST instruct the agent to do X" — does the prose in this
        specific skill file convey X clearly enough?

      Anonymous DeepSchemas provide both write-time validation and review-time
      checks, and they keep the requirement co-located with the file it governs.
      Prefer them over `.deepreview` rules whenever the requirement targets a
      specific file rather than a class of files.

      Both `.deepreview` rules and DeepSchemas reference requirement IDs in
      their `description`, `instructions`, or `requirements` fields.

      ## Anti-patterns to flag

      **Fragile keyword tests for judgment-based requirements.** A test that
      checks `"reuse" in content.lower()` to validate "MUST instruct the
      agent to reuse existing rules" is not deterministic verification — it
      is a keyword search pretending to be one. The word "reuse" could appear
      in an unrelated sentence, be negated ("do NOT reuse"), or be absent
      while the instruction clearly conveys reuse through other wording.
      These requirements need a review rule that can read and evaluate the
      instruction's meaning. Other examples of this anti-pattern:
      - `"parallel" in content` for "MUST launch tasks in parallel"
      - `"again" in content or "repeat" in content` for "MUST re-run after changes"
      - `"without asking" in content` for "MUST automatically apply obvious fixes"

      **Review rules for machine-verifiable requirements.** A review rule
      that asks a reviewer "check whether the config file contains
      `--platform claude`" is wasting reviewer judgment on something
      `assert "--platform" in args` can verify exactly. If the requirement
      specifies a concrete value, path, or structure, use a test.

      See specs/validating_requirements_with_rules.md for more information.

      ## Review checklist

      1. Check that any new or changed end-user functionality has a
         corresponding requirement in `specs/`.
      2. Check that every requirement touched by this change has at least
         one automated test OR at least one `.deepreview` rule validating
         it. **Verify the mechanism matches the requirement type** — flag
         keyword-search tests used for judgment requirements, and flag
         review rules used for machine-verifiable requirements.
      3. Flag any test modifications where the underlying requirement did
         not also change.
      4. For test-validated requirements, verify traceability comments are
         present, correctly reference requirement IDs, and use the standard
         two-line format:
         ```
         # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.5).
         # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
         ```
         Both lines are required. They must appear immediately before the
         `def` line (not inside the method body). If tests have REQ references
         only in docstrings but are missing the formal comment block, flag
         them. If the second line is missing, flag that too.
      5. For rule-validated requirements, verify the `.deepreview` rule's
         description or instructions reference the requirement ID and that
         the rule's scope covers the requirement's intent.

      Produce a structured review with Coverage Gaps, Test Stability
      Violations, Traceability Issues, and a Summary with PASS/FAIL verdicts.

requirement_file_format:
  description: "Validate RFC 2119 compliance, unique IDs, and sequential numbering in requirement spec files."
  match:
    include:
      - "specs/**/*-REQ-*.md"
  review:
    strategy: individual
    instructions: |
      Review this requirements specification file for format correctness.

      Check the following:

      1. **RFC 2119 keywords**: Every requirement statement MUST use at least one
         RFC 2119 keyword (MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
         MAY, REQUIRED, RECOMMENDED, OPTIONAL). Flag any numbered requirement
         that lacks an RFC 2119 keyword — e.g., "The system generates a UUID"
         should be "The system MUST generate a UUID."

      2. **Unique requirement IDs**: Each section heading must follow the pattern
         `### {PREFIX}-REQ-NNN.M: Title` where PREFIX matches the filename prefix
         (e.g., JOBS-REQ for JOBS-REQ-001-*.md). Within each section, requirements
         are numbered lists (1., 2., 3., ...). Flag any duplicate section IDs.

      3. **Sequential numbering**: Within each section, numbered requirements
         should be sequential without gaps (1, 2, 3 — not 1, 2, 4). Flag gaps
         or out-of-order numbers.

      4. **Section ID consistency**: The section ID prefix must match the file's
         naming convention. For example, in `JOBS-REQ-001-mcp-workflow-tools.md`,
         all sections should use `JOBS-REQ-001.X` (not `JOBS-REQ-002.X`).

      5. **Testability**: Each requirement should be specific enough to be
         verifiable — either by an automated test or a review rule. Flag vague
         requirements that cannot be objectively evaluated (e.g., "The system
         SHOULD be fast" — fast compared to what?).

      Output Format:
      - PASS: All requirements are properly formatted.
      - FAIL: Issues found. List each with the section ID, requirement number,
        and a concise description of the issue.

update_documents_relating_to_src_deepwork:
  description: "Ensure project documentation stays current when DeepWork source files, plugins, or platform content change."
  match:
    include:
      - "src/deepwork/**"
      - "plugins/**"
      - "platform/**"
      - "pyproject.toml"
      - "README.md"
      - "README_REVIEWS.md"   # Documents the review system — must stay in sync with src/deepwork/review/
      - "CLAUDE.md"
      - "doc/architecture.md"
      - "doc/mcp_interface.md"
      - "doc/job_yml_guidance.md"  # Describes job.yml runtime behavior — must stay in sync with parser/schema
      - "doc/doc-specs.md"
      - "doc/platforms/**"
      - "src/deepwork/hooks/README.md"
    exclude:
      - "**/__pycache__/**"
  review:
    strategy: matches_together
    instructions: |
      When source files in src/deepwork/, plugins/, or platform/ change, check whether
      the following documentation files need updating:
      - README.md (install instructions, feature descriptions, project overview)
      - README_REVIEWS.md (review system usage, .deepreview config format, strategies, examples)
      - CLAUDE.md (project structure, tech stack, CLI commands, architecture)
      - doc/architecture.md (detailed architecture, module descriptions, data flow)
      - doc/mcp_interface.md (MCP tool parameters, return values, server config)
      - doc/job_yml_guidance.md (job.yml field descriptions, runtime behavior, review cascade)
      - doc/doc-specs.md (doc spec format, parser behavior, quality criteria)
      - doc/platforms/claude/ (Claude-specific hooks, CLI config, learnings)
      - doc/platforms/gemini/ (Gemini-specific hooks, CLI config, learnings)
      - src/deepwork/hooks/README.md (hook system, event mapping, tool mapping)

      Read each documentation file and compare its content against the changed source
      files. Pay particular attention to:
      - Directory tree listings (do they still match the actual filesystem?)
      - CLI command descriptions (do flags, behavior descriptions still match?)
      - MCP tool parameters and return values (do they match the implementation?)
      - Module/class/function descriptions (do they match what the code actually does?)
      - Dependency lists (does pyproject.toml still match what the doc says?)
      - Install/usage instructions (do they still work?)
      - Hook event/tool mappings (do tables match the implementation?)

      Flag any sections that are now outdated or inaccurate due to the changes.
      If the documentation file itself was changed, verify the updates are correct
      and consistent with the source files.
    additional_context:
      unchanged_matching_files: true

update_learning_agents_architecture:
  description: "Ensure learning agents documentation stays current when the learning_agents plugin changes."
  match:
    include:
      - "learning_agents/**"
      - "doc/learning_agents_architecture.md"
    exclude:
      - "learning_agents/**/transcripts/**"
  review:
    strategy: matches_together
    instructions: |
      When files in learning_agents/ change, check whether doc/learning_agents_architecture.md
      needs updating. Read the architecture doc and compare against the changed source files.

      Pay attention to:
      - Plugin structure listings (do they match the actual directory layout?)
      - Skill descriptions (do they match what skills actually do?)
      - Learning cycle descriptions (does the flow still match the implementation?)
      - File format descriptions (do they match actual file formats used?)
      - Configuration examples (do they still work?)

      Flag any sections that are now outdated or inaccurate due to the changes.
      If the doc itself was changed, verify the updates are correct.
    additional_context:
      unchanged_matching_files: true

shell_code_review:
  description: "Review shell scripts for correctness, safety, and project conventions."
  match:
    include:
      - "**/*.sh"
  review:
    strategy: individual
    instructions: |
      Review this shell script against the project's shell scripting conventions.

      Project shell conventions (observed from existing scripts):
      - Shebang: `#!/usr/bin/env bash` (NOT `#!/bin/bash` — required for NixOS compatibility)
      - Safety: use `set -e` or `set -euo pipefail`
      - Variables: UPPERCASE_WITH_UNDERSCORES, always quoted ("$VAR")
      - JSON parsing: use jq with fallback defaults (// empty, // "default")
      - Header comment block: description, usage, input/output, exit codes
      - Section markers: # ==== blocks for logical sections in longer scripts
      - Exit codes: 0 for success, 1 for usage errors, 2 for blocking errors

      Check for:
      - Hardcoded shebang paths (e.g., `#!/bin/bash`) — must use `#!/usr/bin/env bash`
      - Unquoted variables that could cause word splitting or globbing
      - Missing error handling (commands that could fail silently)
      - Unsafe use of eval, unvalidated user input, or command injection risks
      - Portability issues (bashisms that break on other shells, if applicable)
      - Proper use of jq for JSON parsing (not grep/sed on JSON)

      Additionally, always check:
      - **DRY violations**: Is there duplicated logic or repeated patterns across
        sections that should be extracted into a function?
      - **Comment accuracy**: Are all comments (especially header blocks and
        section markers) still accurate after the changes? Flag any comments
        that describe behavior that no longer matches the code.

deepreview_config_quality:
  description: "Review .deepreview configs for rule consolidation, overly broad rules, description accuracy, and correct directory placement."
  match:
    include:
      - "**/.deepreview"
  review:
    strategy: matches_together
    additional_context:
      unchanged_matching_files: true
    instructions: |
      Review the .deepreview config files for structural quality. Check all
      four of the following, across ALL .deepreview files (changed and unchanged):

      ## 1. Rule Consolidation

      Rules that match the same (or nearly the same) set of files SHOULD be
      combined into a single rule — unless merging their instructions would
      make the reviewer's context too large or unfocused. Specifically:

      - Flag rules in the same .deepreview file (or across files at the same
        directory level) whose `match.include` patterns overlap substantially.
      - "Too large" means the combined instructions would exceed ~2000 words
        or cover unrelated concerns that would confuse a single reviewer.
      - If two rules match identical files but one uses a specialized `agent`
        persona, that is a valid reason to keep them separate.

      ## 2. Description Accuracy

      Each rule's `description` field must accurately reflect what the rule
      actually checks. Compare the description to the `instructions` (inline
      or referenced file) and flag any mismatches. For example:

      - A description saying "Review Python files for security" when the
        instructions only check formatting — flag it.
      - A description that is vague or generic when the instructions are
        specific — flag it and suggest a more accurate description.

      ## 3. Overly Broad Rules (Needless Combining)

      The inverse of consolidation: a single rule that matches a broad set of
      files but whose instructions are actually file-specific or path-specific.
      This is a sign the rule should be split into multiple narrower rules.

      Indicators to flag:
      - A rule with a wide `match.include` pattern (e.g., `**/*.py`, `src/**`)
        but instructions that say things like "For files in src/foo/, check X;
        for files in src/bar/, check Y" — these should be separate rules with
        narrower match patterns.
      - Instructions that enumerate specific filenames or paths and assign
        different checks to each — the match pattern should be doing this
        filtering, not the instructions.
      - A rule whose instructions are mostly conditional on which file is being
        reviewed, rather than applying uniformly to all matched files.

      Exceptions (do NOT flag these):
      - Rules where ~70%+ of the instructions apply to all matched files, with
        only minor per-file notes (e.g., "For test files, also check fixtures").
      - Rules using `matches_together` strategy where cross-file analysis is
        the point (e.g., doc-sync rules that compare source and documentation).

      ## 4. Directory Placement

      .deepreview files should live as close as possible to the files they
      govern. If ALL of a rule's `match.include` patterns target files within
      a single subdirectory (e.g., `learning_agents/**`), then the rule
      should likely live in that subdirectory's `.deepreview` file instead
      of the project root. Flag rules that could be moved closer to their
      target files.

      Exceptions (do NOT flag these):
      - Rules that intentionally match files across multiple top-level
        directories (e.g., `src/**` AND `tests/**`).
      - Rules using `all_changed_files` strategy, which are project-wide
        by nature.
      - Rules that reference `additional_context.unchanged_matching_files`
        with patterns spanning multiple directories.

      ## Output Format

      - PASS: No issues found.
      - FAIL: Issues found. List each with the .deepreview file path,
        rule name, which check failed (consolidation / description / overly-broad / placement),
        and a specific recommendation.

job_schema_instruction_compatibility:
  description: "Verify deepwork_jobs job.yml inline instructions are compatible with the job schema."
  match:
    include:
      - "src/deepwork/jobs/job.schema.json"
      - "src/deepwork/standard_jobs/deepwork_jobs/job.yml"
      - "src/deepwork/standard_jobs/deepwork_reviews/job.yml"
      - "src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.*"  # Templates users copy — must match schema
      - "library/jobs/*/job.yml"
  review:
    strategy: matches_together
    additional_context:
      unchanged_matching_files: true
    instructions: |
      When the job schema, standard job definitions, or library job definitions
      change, verify they are still compatible with each other.

      Read src/deepwork/jobs/job.schema.json to understand the current schema.
      Then read each job.yml (standard and library) and check:

      1. **Field references**: Every field name referenced in inline step
         instructions must exist in the schema at the correct level.
         Pay special attention to step_arguments vs workflow vs step fields.

      2. **Required vs optional**: If instructions say a field is required,
         verify the schema agrees. If instructions say a field is optional,
         verify the schema doesn't require it.

      3. **Schema structure**: Any YAML examples shown in inline instructions
         must match the schema's property names and nesting.

      4. **Terminology consistency**: Instructions should use the same field
         names as the schema (e.g., if the schema uses
         "common_job_info_provided_to_all_steps_at_runtime", instructions
         should not call it "description" or "job_description").

      Output Format:
      - PASS: All job definitions are compatible with the schema.
      - FAIL: Incompatibilities found. List each with the file path, line
        reference, the incompatible content, and what the schema actually says.

agents_md_claude_md_symlink:
  description: "Ensure every AGENTS.md file has a sibling CLAUDE.md symlink pointing to it, because Claude Code reads CLAUDE.md but ignores AGENTS.md."
  match:
    include:
      - "**/AGENTS.md"
  review:
    strategy: individual
    instructions: |
      Claude Code reads CLAUDE.md for project context but does not read AGENTS.md.
      Every AGENTS.md file MUST have a sibling CLAUDE.md that is a symlink pointing
      to AGENTS.md, so that Claude Code picks up the same content.

      Check whether a CLAUDE.md symlink exists in the same directory as the matched
      AGENTS.md file. If it is missing or is not a symlink to AGENTS.md, create it:

        ln -sf AGENTS.md <dir>/CLAUDE.md

      The symlink target MUST be the relative path "AGENTS.md" (not an absolute path),
      so the link remains valid after the directory is moved or cloned.

      Output Format:
      - PASS: CLAUDE.md symlink exists and points to AGENTS.md.
      - FAIL: Symlink missing or incorrect — describe the current state and the fix applied.

nix_claude_wrapper:
  description: "Ensure flake.nix always wraps the claude command with the required plugin dirs."
  match:
    include:
      - "flake.nix"
      - ".envrc"
  review:
    strategy: matches_together
    instructions: |
      The nix dev shell must ensure that running `claude` locally automatically
      loads the project's plugin directories via `--plugin-dir` flags. Verify:

      1. **Wrapper exists**: flake.nix creates a wrapper (script or function)
         that invokes the real `claude` binary with extra arguments.

      2. **Required plugin dirs**: The wrapper MUST pass both of these
         `--plugin-dir` flags:
         - `--plugin-dir "$REPO_ROOT/plugins/claude"`
         - `--plugin-dir "$REPO_ROOT/learning_agents"`

      3. **PATH setup**: The wrapper must be discoverable — either via a
         script placed on PATH (e.g. `.venv/bin/claude`) with `.envrc`
         adding that directory to PATH, or via a shell function/alias.

      4. **Real binary resolution**: The wrapper must resolve the real
         `claude` binary correctly, avoiding infinite recursion (e.g. by
         stripping the wrapper's directory from PATH before lookup).

      Output Format:
      - PASS: The claude wrapper is correctly configured with both plugin dirs.
      - FAIL: Describe what is missing or broken.

mcp_interface_consumer_sync:
  description: "When MCP tool interfaces change, verify that skills, hooks, and platform content still reference correct parameter names, types, and behavior."
  match:
    include:
      - "src/deepwork/jobs/mcp/tools.py"
      - "src/deepwork/jobs/mcp/schemas.py"
      - "src/deepwork/jobs/mcp/server.py"
  review:
    strategy: matches_together
    additional_context:
      unchanged_matching_files: true
    instructions: |
      When the MCP tool interfaces (tools.py, schemas.py, server.py) change,
      verify that downstream consumers still accurately describe the MCP
      interface. Check each of these files for stale parameter names, removed
      fields, renamed concepts, or outdated behavior descriptions:

      - platform/skill-body.md
      - plugins/claude/skills/deepwork/SKILL.md
      - plugins/gemini/skills/deepwork/SKILL.md
      - plugins/claude/hooks/post_compact.sh
      - doc/mcp_interface.md

      For each file, compare any MCP parameter names, tool names, response
      fields, or workflow behavior descriptions against the actual schemas
      and tool implementations. Flag anything that no longer matches.

      Output Format:
      - PASS: All consumer files are consistent with the current MCP interface.
      - FAIL: List each inconsistency with the file, the stale content, and
        what it should say based on the current implementation.
