robcsaszar AI Forge Recap
Audit a skill or agent by reading its actual implementation and reporting what it really does — independent of what the description claims. The description is a claim; the body is the ground truth.
What to Read
Use the path provided or resolved by the environment. If not found, report "Not found" and stop.
For skills: also read any references/ files marked MANDATORY READ — behaviors that live outside the main body still count.
If a references/ directory exists but no files are marked MANDATORY READ, include this note in Undeclared behaviors: "references/ directory present but no MANDATORY READ triggers — possible Orphan References pattern."
For agents: read the full .agent.md file including frontmatter (model, tools, etc.).
For other file types (.instructions.md, CLAUDE.md, standalone prompts): read the full file; if the file has a leading comment or description block, treat it as the "description claim" to compare against the body.
What to Compare
The description makes four implicit claims. Check each against the body:
- WHAT it does — does the body do this, or something adjacent?
- WHEN to use it — do trigger phrases match actual entry conditions?
- Keywords — do searchable terms reflect what the body covers?
- Scope — does the description under- or over-state coverage?
Also scan for undeclared behaviors: things the body does that the description never mentions. Focus on locations where iterative edits silently accumulate new behavior: NEVER rules, phases/steps, skip/exit conditions, reference-loading triggers, confirmation loops, conditional output sections, and tool/skill invocations.
Short targets (<15 lines body): Focus on scope accuracy over exhaustive four-claim comparison. A minimal body with a matching description is Aligned — don't manufacture drift from brevity.
Before writing your verdict, ask: Would an agent picking from descriptions alone make the right call? If the description would misroute, that's Significant drift regardless of how small the wording gap appears.
Output Format
## Recap: <name>
**Description claims:** [one-line summary of what description promises]
**Body actually does:** [one-line summary derived independently from reading the body]
**Drift found:**
- [specific discrepancy]
(or "None found")
**Undeclared behaviors:**
- [behavior in body not mentioned in description]
(or "None found")
**Verdict:** Aligned / Minor drift / Significant drift
Post-Recap Actions
After writing the recap block, classify the findings into two buckets:
- Frontmatter drift: discrepancies in the
nameordescriptionfields - Body drift: behavioral discrepancies or undeclared behaviors
If neither bucket has findings, output "No drift found." and stop — do not show the action menu.
Otherwise, show only the options relevant to what was found:
(f)ix frontmatter — apply corrected name/description fields via ai-forge-apply [only if frontmatter drift]
(u)pdate body — hand off to ai-forge-update with drift loaded [only if body drift]
(j)udge — run ai-forge-judge for quality scoring [always]
(r)eview — run ai-forge-review for interactive design check [agents only]
(f) Fix frontmatter
Produce a numbered findings list covering only the drifted fields. Each item must include the current value and the corrected value:
1. name: "<current>" → "<corrected>"
2. description: "<current>" → "<corrected>"
Then invoke ai-forge-apply on that list.
(u) Update body
Invoke ai-forge-update and pass the recap output as pre-loaded context. State explicitly that Phase 0 is already complete so ai-forge-update skips directly to Phase 1 change elicitation.
(j) Judge
Invoke ai-forge-judge on the recapped artifact.
(r) Review
Invoke ai-forge-review on the recapped agent. Only available for agent definitions.
Verdict Criteria
Minor drift: Description is imprecise but not misleading. The artifact would still be selected for the right task.
Significant drift: Description would cause the artifact to be selected for the wrong task, OR the agent would miss a key behavior because the description omits it.
An incomplete description (missing behaviors) differs from a wrong description (claiming behaviors that don't exist). Flag both, label them separately.
NEVER
NEVER start your "body actually does" summary by paraphrasing the description Instead: Read the body first, form an independent summary, then compare to the description. Why: Starting from the description anchors you to its framing — you'll miss drift because your summary will match it by construction.
NEVER skip MANDATORY READ reference files Instead: Load them before forming your assessment. Why: Key behaviors — NEVER rules, decision trees, phase logic — often live in references, not the main body.
NEVER mark a description as "wrong" when it's merely "incomplete" Instead: Label each discrepancy explicitly: incomplete vs. wrong. Why: The remediation differs — incomplete descriptions need additions; wrong descriptions need corrections.
NEVER report drift on formatting or style differences alone Instead: Focus on semantic mismatches — does the description promise different behavior than the body delivers? Why: A description that says "audit" while the body says "evaluate" is stylistic, not drift. Reporting it floods the output with noise.
NEVER flag behaviors inherited from the pattern or calling convention as "undeclared" Instead: Only flag behaviors the body adds beyond what any skill/agent of this pattern would do. Why: Every Tool-pattern skill has a NEVER list and output format — these aren't undeclared, they're structural.
NEVER conflate description brevity with scope understatement Instead: A short description that accurately covers the core purpose is Aligned, even if the body is long. Why: Descriptions are capped at 1024 chars; they summarize, not exhaustively list. Judge routing accuracy, not word count parity.