docs-impact-classifier

Single responsibility: given a PR diff and the .apm/docs-index.yml corpus map, emit ONE classification verdict.

This skill is the cost gate for the entire docs-sync system. ~70% of PRs should exit at verdict no_change with zero panel spawn.

Architecture

This is a 3-layer funnel inside a single skill invocation:

• L0 deterministic path gate -- pure file-path matching, no LLM.
• L1 symbol extraction + corpus grep -- pure text processing, no LLM.
• L2 LLM classifier -- bounded ~8 KB context envelope, 1 call.

The skill returns the verdict from the earliest layer that can decide.

Step 1: L0 deterministic path gate (no LLM)

Read .apm/docs-index.yml to load no_impact_paths[] and user_surface_paths[]. Get the changed file list from the PR diff (gh pr diff --name-only).

if every changed file matches no_impact_paths AND none match user_surface_paths:
    return {verdict: "no_change", confidence: "high", source: "L0", scope_pages: []}

This handles:

• Test-only PRs (tests/**)
• CI workflow PRs (.github/workflows/**)
• Doc-only PRs (docs/**) -- out of scope, docs-sync doesn't review docs PRs
• Primitive-only PRs (.apm/**)
• Script and meta PRs

Expected hit rate: ~70% of PRs short-circuit here.

Step 2: L1 symbol extraction + corpus grep (no LLM)

If L0 did not exit, extract user-observable symbols from the diff:

• CLI command names -- grep diff for ^@click.command, ^@cli.command, or any apm <verb> mention in added/removed lines.
• Flag names -- grep diff for ^@click.option, --[a-z-]+ patterns.
• Public API symbols -- added/removed def <name> in src/apm_cli/__init__.py or src/apm_cli/api/**.
• Schema keys -- added/removed keys in apm.yml, apm.lock.yaml, apm-policy.yml parsers.
• Error strings -- added/removed string literals in user-facing error paths (look for _rich_error, click.echo, raise ... Error().