holocron/plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md

source_keys

source_keys
context7-websites-code-claude claude-code-plugins-docs claude-code-subagents-docs context7-github-en-copilot github-custom-agents-configuration

Finding Criteria

Every FAIL and SUGGESTION criterion, for every qualitative dimension, and nothing else. The reasoning each criterion stands on, its worked examples and its house rules stay in that dimension's rubric, which Step 3 loads only for a dimension this file puts in play.

Two rules on using it:

• A criterion that plainly applies is a finding. Write it up citing file and line.
• A criterion that might apply, or whose call the wording here does not settle, is a reason to load that dimension's rubric — never a reason to drop the candidate. This file decides which rubrics to read; it does not settle a close call on its own.

description — references/description-quality.md

Flag as FAIL if:

• Over 400 characters. Measured on the folded YAML value, not the raw source lines. validate.sh reports the number; do not re-derive it, but do point the Fix at what to cut. Agent descriptions have no platform-documented ceiling of their own, so 400 is the only hard limit there is — do not go looking for a backstop behind it.

• Internal mechanics appear in the description. Any of:

  • capability enumeration or a feature list;
  • output-format detail ("Produces a compact findings report with Why and Fix per finding");
  • composition or architecture notes ("composes X rather than duplicating Y", "a cross-cutting shared agent", "the human-facing entry point", "replaces the old flat invocation");
  • implementation detail ("self-validates via a bundled deterministic script").

  None of it can change a routing decision and all of it is preloaded. Kyberforge.CompositionNote catches the common phrasings deterministically; the rest is judgment. This is the rule that deflates a description, so apply it before reaching for length.

• The same trigger stated twice in two registers — a verb list, then the same verbs re-quoted as user phrasings, usually in the same order. One register, whichever routes better.

• Descriptive rather than imperative phrasing (This agent ..., This is the ...). Kyberforge.DescriptionOpener catches any opener matching ^This.

• Vague capabilities ("helps with agents" where "audits an agent definition pair" was available). Kyberforge.VagueWording catches the known filler; imprecision outside that list is judgment.

• Use proactively in a Copilot or vendor-neutral description. KyberforgeCopilot.ProactivePhrase catches it. The phrase steers the Claude Code runtime and does nothing anywhere else, so in a .agent.md it is preloaded text that buys no behaviour.

• Trigger-list, boundary or indirect-trigger content on a hand-invoked agent — see Step 0 of references/description-quality.md.

Flag as SUGGESTION if:

• Over 250 characters but at or under 400. This tier is what moves the corpus average; the FAIL tier only stops outliers. Report it rather than treating a 399-character description as clean.
• A near-miss exclusion is present but targets a weak near-miss.
• An indirect trigger is present and warranted but could name the omitted phrasing more precisely.

An unresolved boundary target is not graded here. validate.sh resolves boundary targets for agent files at both scopes and tiers the verdict itself — route notation (/name, an arrow form) is an ERROR, the bare prose form a SUGGESTION unless a second target in the same sentence resolves. Step 1 has already filed it under ### Structure at that tier. Take the script's verdict rather than re-resolving the name by hand, and do not re-grade it under description: a hand-walk over a different universe can contradict the script, and re-grading puts one target in the report twice. What is left to judgment is semantic and the script cannot reach it: whether a target that does resolve is the right sibling to exclude, and whether a clause naming no target at all ("examine the files manually") should have named one.

body, delegation and comment-discipline — references/body-and-delegation.md

Flag as FAIL if:

• The body restates a procedure owned by a skill the agent can invoke — Fix: invoke <skill> instead
• A sentence answers "no" to the core test — it is padding
• A decision point presents a menu of options with no default
• An instruction repeats content already in the description
• Frontmatter comments are template scaffolding rather than instruction, or are HTML comments at plugin/APM scope
• A prescriptive sequence is used where flexibility is fine, or the reverse

Flag as SUGGESTION if:

• The body does not open with a direct role instruction
• The body specifies no error handling — nothing tells the agent what to do with malformed, missing or contradictory input
• The job the agent describes is unbounded, or bounded only implicitly
• A rationale is missing from a rule the agent is expected to enforce — present but unexplained
• Comments are useful but verbose enough to bury the field they annotate

Never report an agent body as too long on a word count. ADR-0020 gates a skill body at 600/900 words and deliberately gates an agent body at nothing, because an agent body becomes the system prompt of a fresh context rather than competing with a live conversation. No number exists to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit, which validate.sh already reports as a SUGGESTION. Length is judged through the delegation FAIL above instead.