pitfalls-add - SKILL.md Agent Skill

name: pitfalls-add description: "Add a new entry to the known-pitfalls catalog that pitfalls-check audits against. Verifies the correct pattern against the Strapi source before adding, and confirms with the user. Use when you have found a documentation mistake worth catching automatically in future reviews." argument-hint: "[--non-interactive] [--no-log] <description of the pitfall, or a pitfalls-check / code-verify finding to promote>" user-invocable: true

/inki:pitfalls-add: add an entry to the known-pitfalls catalog

The pitfalls-checker agent is read-only: it consults the catalog but never edits it. This skill is the writing counterpart: it adds a new, verified entry to ${CLAUDE_PLUGIN_ROOT}/references/prompts/integrity-known-pitfalls.md so the mistake is caught automatically in every future review.

Step 0: Parse arguments

If $ARGUMENTS contains --help or -h, print usage and stop, per ../../references/help.md. Do not modify the catalog.

Otherwise, from $ARGUMENTS, detect --non-interactive (canonical), aliases --auto-approve, --auto, --yes, -y, --no-questions-asked (all equivalent) → AUTO=true. What remains describes the pitfall: either free text, or a finding copied from a pitfalls-check / code-verify report.

Logging: unless --no-log is passed, write this skill's report to the run log per ../../references/logging.md (--log-dir <path> and --short-log are also accepted). This skill normally runs standalone (it creates its own run directory); if ever invoked as part of an orchestrator, write into that run's existing directory instead of creating a new one.

Step 1: Derive the three required fields

Every catalog entry needs:

Hallucinated pattern: what the wrong content says (the version to catch).
Correct pattern: what the code actually does.
Context: why the mistake happens and when to watch for it.

Extract these from the input. If any is missing or unclear, ask the user (do not invent the correct pattern).

Step 2: Verify the correct pattern against the source

Do NOT add an unverified pattern: a wrong catalog entry would generate false positives forever. Confirm the "correct pattern" against the actual strapi/strapi source (a local clone if available, otherwise a raw GitHub fetch), the same way code-verify does. If it cannot be verified, say so and stop; offer to add it as a clearly-marked unverified entry only if the user insists.

Step 3: Choose the category

Read the catalog and pick the matching category table (e.g. "Strapi v5 identifiers", "Lifecycle and boot sequence"). If none fits, create a new category section following the existing format.

Step 4: Show the proposed entry and confirm

Display the exact row to be added, under which category:

Category: <name>
| <hallucinated> | <correct> | <context> |

If AUTO=false (default), ask for confirmation before writing. If AUTO=true, skip the prompt (the source verification in Step 2 is the safety gate).

Step 5: Add the entry

Add the row to the chosen table (or the new category section), preserving the file's existing Markdown formatting. Do not reorder or rewrite existing entries.

Step 6: Report

Confirm what was added and where. If the catalog lives under a synced reference, remind the user that the canonical copy may need the same edit if a sync rule applies (the catalog is a plugin reference, edited in place here).

Rules

Never add an unverified "correct pattern". Verification against the source is mandatory (Step 2).
Append only; never edit or remove existing catalog entries.
This is the only inki skill allowed to write the pitfalls catalog. The pitfalls-checker agent stays strictly read-only.