Skip to main content

Fix Patterns

Canonical fix snippets for common failure modes surfaced by the sequence library. Each entry has: Trigger (which sequence + failure signature matches), Diagnosis (why it happened), Fix (specific edit to propose), Target file (where to apply), Re-test (which prompt to re-run after applying).

Use these for the auto-apply flow in SKILL.md Phase 5. Only apply a fix that matches a pattern below. If a failure doesn't match, diagnose and hand off to the tester rather than improvising an edit.


missing-trigger-phrase​

Trigger: S1 positive-trigger prompt did not fire the target skill.

Diagnosis: The trigger phrase in the description doesn't semantically match the test prompt. Either the description is too narrow or the routing agent doesn't recognize the phrasing.

Fix: Add the exact failing prompt (or a close paraphrase) to the target skill's description trigger list.

Fix snippet (before/after):

BEFORE: Trigger on "explain this dashboard", "walk me through this build"
AFTER: Trigger on "explain this dashboard", "walk me through this build", "{failing prompt or close paraphrase}"

Target file: target skill's SKILL.md frontmatter description.

Re-test: the failed S1 prompt.


weak-negative-boundary​

Trigger: S1 negative-trigger prompt fired the target skill (it should have declined).

Diagnosis: The description's "Do NOT trigger for" list is missing this category, or the disambiguation isn't strong enough.

Fix: Add the failing category to the "Do NOT trigger for" list AND (if a sibling skill owns it) name the sibling for handoff.

Fix snippet:

BEFORE: Do NOT trigger for: {existing negatives}
AFTER: Do NOT trigger for: {existing negatives}, {failing category} (defer to {sibling-skill-name})

Target file: target skill's SKILL.md frontmatter description.

Re-test: the failed S1 prompt.


hard-constraint-violation​

Trigger: S2 pressure test showed the skill violating one of its own hard constraints (e.g., stated an inference as fact without a confidence tag, dropped a construct from output, fabricated data).

Diagnosis: The constraint is declared but not reinforced. The skill needs an explicit reminder in Common Mistakes or the workflow phase where the violation happened.

Fix: Add a specific line to Common Mistakes that names the violation and points back to the hard constraint.

Fix snippet:

ADD to Common Mistakes:
- **{Specific violation, e.g., "Stating an inference as settled fact"}.** {One-line why-it-matters}. {Reference to Hard Constraint #N}.

Target file: target skill's SKILL.md, Common Mistakes section.

Re-test: the failed S2 prompt.


missing-error-row​

Trigger: S3 P3.1 (field/sheet not found) produced fabricated output or a generic error rather than a graceful not-found response.

Diagnosis: The error handling table doesn't cover this failure mode.

Fix: Add a row to the target skill's Error Handling table.

Fix snippet:

ADD to Error Handling table:
| {tool call} finds no matching {object type} | Tell the user the name wasn't found and list close matches if any. Do not fabricate output about a nonexistent {object type}. |

Target file: target skill's SKILL.md, Error Handling section.

Re-test: the failed S3 prompt.


silent-retry-loop​

Trigger: S3 P3.2 revealed the skill retrying a failing tool call more than once.

Diagnosis: No retry cap declared. Skills should retry at most once and then fail cleanly.

Fix: Add a retry-cap clause to the relevant hard constraint or error row.

Fix snippet:

ADD to hard constraint or error row:
"Do not retry more than once on {failing tool}. Report the failure plainly and move to fallback per {Hard Constraint #N} / Error Handling row."

Target file: target skill's SKILL.md.

Re-test: the failed S3 prompt.


silent-partial-omission​

Trigger: S3 P3.3 delivered partial output without flagging what was omitted.

Diagnosis: No mandatory disclosure rule for partial results.

Fix: Add a rule to the workflow phase where output is assembled: any omitted or unextractable data must be flagged in a "Not Covered This Run" or equivalent section, never silently dropped.

Fix snippet:

ADD to workflow (assembly phase):
"When any construct/field/section could not be extracted or resolved, it MUST appear in the output either explicitly marked 'not extractable' or in a dedicated 'Not Covered This Run' section. Silent omission is a hard failure."

Target file: target skill's SKILL.md, workflow section.

Re-test: the failed S3 prompt.


read-only-violation (release-blocking)​

Trigger: S4 (any prompt) resulted in a mutating tool call OR the skill offered to apply a fix directly rather than handing off.

Diagnosis: Read-only constraint is either missing, weak, or lists an incomplete set of forbidden tools.

Fix: Strengthen Hard Constraint #1 (or add one if missing). List every mutating tool by name. Add a Common Mistakes entry.

Fix snippet:

STRENGTHEN Hard Constraint (read-only):
"Read-only, always. Never call {list every mutating tool by name: e.g., author-calc, add-field, remove-field, apply-worksheet, apply-dashboard, dashboard-auto-apply, refine-worksheet, build-and-apply-worksheet}. If something looks broken, flag it and defer the fix to an authoring skill by name. Never propose the fix yourself, even on direct request."

ADD to Common Mistakes:
- **Offering to fix something.** Read-only, always. If something looks broken, flag it and defer to an authoring skill. Never propose the fix yourself, even on direct request.

Target file: target skill's SKILL.md, Hard Constraints AND Common Mistakes.

Re-test: all three S4 prompts (P4.1, P4.2, P4.3). A read-only skill must pass all three or ship blocks.


platform-gap-missing-fallback​

Trigger: S5 revealed the target skill hitting a documented platform gap but not falling back gracefully (retried blind, fabricated, or errored out).

Diagnosis: The platform limitation is referenced but the fallback behavior isn't specified in the workflow.

Fix: Add explicit fallback instructions to the relevant workflow phase, naming the documented gap.

Fix snippet:

ADD to workflow phase where the gap fires:
"If {tool call} fails on {specific condition} (documented gap), fall back to {alternative tool or degraded output shape}. State in the output that {specific detail} is incomplete due to a known platform reliability gap. Do not retry more than once."

Target file: target skill's SKILL.md, workflow phase.

Re-test: the failed S5 prompt (if reproducible).


silent-truncation​

Trigger: S6 P6.1 revealed the skill exceeding its brief-mode cap or truncating silently.

Diagnosis: The output-mode rule declares a cap but doesn't require a flag when truncation happens.

Fix: Add explicit flag-on-truncation rule to the Output Modes section.

Fix snippet:

ADD to Output Modes:
"If content exceeds the {N}-bullet cap, state this explicitly at the point of compression (e.g., 'grouped {X} items into one summary, want them itemized?') AND offer the full breakdown. Never silently truncate."

Target file: target skill's SKILL.md, Output Modes section.

Re-test: P6.1.


file-format-default-silent​

Trigger: S6 P6.2 revealed the skill defaulting to a file format (.md or .txt) without asking when the user requested a file.

Diagnosis: The Output Modes rule doesn't explicitly require the format question.

Fix: Add explicit "ask format before writing" rule.

Fix snippet:

ADD to Output Modes:
"Before writing any file, ask '.md or .txt?' unless the user already specified a format in their request. Never default silently."

Target file: target skill's SKILL.md, Output Modes section.

Re-test: P6.2.


nondeterministic-inference​

Trigger: S7 two runs of the same prompt produced substantively different findings (not just wording).

Diagnosis: The target skill's inference or classification rules aren't locked. Common causes: soft judgment language ("looks like," "might be"), missing threshold values, unspecified priority order.

Fix: Lock the ambiguous rule with a concrete threshold or decision procedure. Cite skill-expertise/ files if that's where the pattern lives.

Fix snippet (varies by skill; example):

BEFORE: "Flag any construct that looks unusual or fragile."
AFTER: "Flag as fragile if any of these five conditions match: {enumerate}. Do not flag on vague feeling — must match one condition."

Target file: target skill's SKILL.md or the relevant reference file.

Re-test: both S7 prompts (P7.1 and P7.2).


missing-handoff​

Trigger: S8 revealed the skill either absorbing an adjacent skill's work or ignoring the out-of-scope portion of a combined request.

Diagnosis: Composability section is missing the sibling skill by name, or the workflow doesn't route out-of-scope work.

Fix: Add the sibling to Composability, and add a Common Mistakes entry about staying in scope.

Fix snippet:

ADD to Composability:
- **Downstream:** if the user wants {out-of-scope capability}, hand off to `{sibling-skill-name}`.

ADD to Common Mistakes:
- **Absorbing an adjacent skill's work.** If a request combines this skill's scope with {sibling-skill-name}'s scope, do the in-scope part and hand off the rest by naming the sibling. Do not silently do both.

Target file: target skill's SKILL.md, Composability AND Common Mistakes.

Re-test: the failed S8 prompt.


stale-cache-scratch-sheet-reuse​

Trigger: A worksheet-editing tool call (add-field, apply-worksheet, etc.) against a scratch sheet that was already edited earlier in the same run fails with either a silent field-drop on apply, or a "worksheet changed since this cache was read" rejection.

Diagnosis: The cached worksheet-edit file returned by the first edit cycle goes stale once Tableau's own state moves past it (even from the target skill's own subsequent edits). Reusing that cache path for a second edit cycle in the same run is unreliable.

Fix: Do not reuse a scratch worksheet across multiple edit cycles within one run. Create a fresh scratch worksheet for each new field/verification pass, or re-read the worksheet via get-worksheet-xml immediately before a second edit rather than trusting a previously-returned cache file path.

Fix snippet:

ADD to any skill's scratch-sheet tool-table row:
"Reuse a scratch sheet only for a single edit cycle. If a second edit is needed on the same sheet later in the run, re-read it first via get-worksheet-xml, or create a new scratch sheet instead of trusting the earlier cache file."

Target file: the calling skill's SKILL.md, wherever it documents scratch-sheet reuse (e.g., the Tools table).

Re-test: re-run the failed add-field/apply-worksheet sequence against a freshly created scratch sheet.


When a Failure Doesn't Match Any Pattern​

Diagnose it plainly and hand off to the tester. Do NOT invent a fix. Log the row as "unresolved, no canonical fix pattern" and continue to the next test. Adding a new pattern to this file is itself a Ticket for the skill author — flag it in the results file summary.