Synthesis Anti Shortcuts

Synthesis Anti-Shortcuts

A discipline for catching the lazy-shortcut antipattern in AI-assistant output before it ships. The pattern is simple: when a user states "best solution, no shortcuts," the agent often produces a draft that looks like good engineering but quietly substitutes a lower-effort path. The substitution hides under reasonable-sounding vocabulary — "for now," "minimal diff," "backward compatible," "out of scope," "archive value." This skill names those costumes and provides the protocol to strip them out.

The pattern is not unique to one model or one user. It is a structural failure mode of agents trained on conservative defaults — minimize change, hedge claims, defer hard choices. Those defaults are correct when no one has said otherwise. They are wrong, and quietly harmful, when the user has explicitly removed them from the constraint set and the agent overrides that instruction with its trained safety preference.

This skill is the methodology. The operational catalog in scripts/scan_output.py is the extract — a phrase scanner that any agent or pipeline can run against draft output. The detailed catalog with rationale, the constraint-first protocol with a worked example, the sub-agent dispatch and acceptance rules, and the anonymized case studies all live in references/ and load on demand.

When to Apply

• Before generating any non-trivial implementation plan, design recommendation, or multi-option analysis
• Before accepting a sub-agent's report — especially when the sub-agent self-flags a tradeoff
• Before committing prose to public-facing artifacts where reputation is at stake (READMEs, blog posts, marketing copy, OSS docs)
• Before responding when the user has explicitly stated "complete this, no shortcuts," "best solution," or equivalent
• As part of a pre-response self-check on any draft that touches code, content, or strategy

When NOT to Apply

• Trivial single-line changes where the implementation is obvious
• Genuine constraint-neutral decisions where the user's input is actually required (e.g., product direction, scheduling, stakeholder facts the agent cannot know)
• Discussions where the agent is teaching about shortcuts, not committing one (the skill recognizes quoted and discussion-mode usage)

The Pattern

Six surface presentations recur across incidents. The underlying behavior is the same in each: a choice was made to avoid harder work because the harder work felt risky, even though the user had explicitly removed that risk from the decision set. Pattern recognition matters more than memorizing any single phrase.

Each costume sounds reasonable in isolation. Each is the same shortcut wearing different clothes. The full catalog with rationale per phrase lives in references/costume-vocabulary.md.

The Methodology

Eight procedures, applied in order on non-trivial work. Each is small. Together they catch the pattern before it ships.

1. The Constraint-First Protocol

Before generating approaches, write the constraints. List the user's stated goals AND non-goals from the current conversation, the project's persistent context files, the workspace's agent-instruction files, and the global agent-instruction files. Then — and only then — generate approaches.

Any pro that violates a stated constraint cannot appear in the analysis. If "backward compatibility is not a goal" is in the constraints, the pro "backward compatible — existing tests pass unchanged" is forbidden. The constraint list functions as a filter on the option space, not a checkbox after the fact.

A worked example, including the constraint-extraction order and the forbidden-criteria mapping, lives in references/constraint-first-protocol.md.

2. The Decision-vs-Asking Distinction

Two question shapes look alike but behave differently. The decision is whether the user's stated constraints determine the answer.

Asking is appropriate when constraints leave a real choice open. Sequencing, scope, product direction, stakeholder facts the agent cannot know — these deserve a real question, asked briefly.

Asking is the lazy-shortcut pattern when constraints already determine the answer. "Should I remove the backward-compat re-export?" after the user has said "backward compatibility is not a goal" is the shortcut. The polite framing — "Recommendation: X. Your call?" — is the costume.

The protocol: before drafting any question to the user, scan recent conversation, project context, and global rules for constraints that might determine the answer. If a constraint determines it, do not draft the question. Execute on the constraint. Report what was done.

3. The Costume Vocabulary

Memorize the seven category labels above. When drafting analysis or reading a sub-agent's report, scan for phrases that match any category. When a match appears, ask: is this phrase a real engineering constraint here, or is it a costume covering avoidance?

The test: did the user, explicitly or via standing constraints, ask the agent to optimize for the thing this phrase implies? If yes, the phrase is legitimate. If the user asked for the opposite — "best, most flexible, robust, maintainable solution; no shortcuts" — the phrase is a costume. Strip it from the draft.

The full per-phrase catalog with category, rationale, and replacement framings lives in references/costume-vocabulary.md. The operational extract is in scripts/scan_output.py.

4. Sub-Agent Dispatch Hygiene

Dispatching a sub-agent with a brief that contains costume vocabulary licenses the sub-agent to produce half-applied work. The brief's framing becomes the sub-agent's permission slip.

Phrases that should NOT appear in a sub-agent dispatch brief:

• "Keep changes minimal"
• "Tinting, not redesigning"
• "Don't break the existing layout"
• "Conservative pass"
• "Light touch"
• "Surgical change"

Replacement framing names the job at full size. Instead of "tint the chrome from accent-A to accent-B, keep diffs minimal," say "apply the new accent everywhere it semantically belongs; the existing layout is the canvas, the accent is the new layer." The sub-agent now has license to do the full job, not a partial one.

Brief size is the second dispatch control. A brief carries at most five deliverables. Larger briefs reliably fail — the sub-agent exhausts its execution budget in late-stage verification and stalls against the platform's dispatch timeout, or returns partial work with the remainder self-reported as follow-up. A seven-deliverable brief (substrate code + API + UI + config + tests + docs + verification) is not one dispatch; it is two or three. Split substantial phases into focused dispatches, run in parallel or in sequence, and plan the split up front — at dispatch time, not after the first stall. The failure is symmetric with the vocabulary rule: an oversized brief produces the same half-applied work that costume vocabulary licenses, with the timeout supplying the excuse.

Full dispatch protocol lives in references/sub-agent-hygiene.md.

5. Sub-Agent Acceptance Audit

When a sub-agent returns, scan its report for the same costume vocabulary you would scan in your own draft. Sub-agents inherit the same conservative defaults. A sub-agent's "I left X for minimal diff" is the same pattern as the orchestrator's own deferral.

The check on every sub-agent return:

1. Read the report including any self-flagged tradeoffs.
2. Scan for costume vocabulary (run the scanner, or scan by eye against the catalog).
3. For each match, ask: would the user, given stated constraints, consider this acceptable? Not "would a reasonable engineer consider this acceptable" — the user's standard is the relevant one.
4. If the answer is "no, the sub-agent left work undone," the orchestrator finishes the job. Either redirect the sub-agent or do it directly. Do not propagate the deferral.

6. Pre-Response Self-Check

Before sending any draft analysis, recommendation, or implementation plan:

1. Scan the draft for costume vocabulary across all seven categories.
2. For each match, classify: real constraint or costume?
3. For each costume, rewrite. The rewrite executes on the actual goal, not the safer-feeling reframe.
4. If the draft ends with a question, verify the question is constraint-neutral (item 2 above).
5. Only then send.

The scanner at scripts/scan_output.py automates step 1. The classification at step 2 is judgment; the catalog at references/costume-vocabulary.md supports it.

7. The Capability-Limit Probe

When a tool call fails, classify the failure before reporting it. There are two kinds, and they call for opposite responses.

• A guardrail is deliberate: a permission the user withheld, a safety gate, an approval step, an action reserved for a human. Never route around it. Reporting it and stopping is the correct outcome.
• A capability gap is incidental: an unconfigured app, an ungranted scope, an unset credential, a feature the current transport does not expose. It is a problem to solve, not a boundary to respect.

Treating the second like the first is the shortcut. It wears the costume of discipline - "I won't work around that" sounds principled - while delivering less than the task required. Agents holding strong, correct rules about not bypassing governance gates are the most prone to it, because the rule generalizes itself onto plumbing where it does not belong.

On a capability gap, before reporting:

1. Name the exact mechanism that failed - the error, the missing scope, the absent configuration. "It didn't work" is not a diagnosis.
2. Enumerate the alternative paths. Another tool that reaches the same surface; another transport; an interface the user is already authenticated to; a configuration change that would unblock the primary path permanently rather than once.
3. Separate what you can do from what only the user can do. Console changes, credential grants and admin approvals belong to the user; determining precisely which change is needed belongs to you. Handing over a diagnosis is help; handing over the problem is not.
4. Report options with a recommendation, never the limitation alone. If a workaround carries risk, surface it and let the user decide. Silently considering and discarding a workaround is the same failure in a quieter form.

The test: would a capable colleague, told "the connector can't send," have stopped there? If the honest answer is that they would have asked "then what else can?", the report was premature.

8. The Maintenance Loop

The catalog grows. When a new costume appears in production output, the loop is:

1. Document the incident as a case study. The incident is the data; the documented teardown is the artifact that survives context loss.
2. Extract the new phrase, category, and rationale.
3. Update references/costume-vocabulary.md with the new entry.
4. Update scripts/scan_output.py if the embedded catalog should detect the phrase.
5. (Optional) Regenerate any operational catalog files that consume this skill.

The methodology stays stable. The catalog refreshes as the failure modes evolve. The anonymized case studies in references/case-studies.md are the durable record of where each entry came from.

How the Pieces Fit

SKILL.md (this file)
   |
   |-- references/costume-vocabulary.md      Full phrase catalog with rationale
   |-- references/constraint-first-protocol.md  Worked-example procedure
   |-- references/sub-agent-hygiene.md       Dispatch + acceptance rules
   |-- references/case-studies.md            Anonymized incident teardowns
   |
   |-- scripts/scan_output.py                Standalone scanner (Python 3, stdlib + pyyaml)

A reader who installs only this skill can apply the methodology end-to-end. The references load on demand; the scanner runs standalone or as a hook in any agent platform.

Relationship to Other Skills

This skill is methodology. It pairs naturally with the synthesis skills that produce the artifacts it audits.

• synthesis-grounding-discipline — The truth-side companion. This skill catches output that does less than the work requires; grounding discipline catches output that claims more than the evidence supports — confabulated events, quotes with no tool-surfaced source, stale cached facts, absences established by a broken probe. One output can fail both at once: a fabricated "already handled" is a shortcut and a grounding failure in the same sentence.
• synthesis-thinking-framework — Foundational reasoning methodology. The constraint-first protocol is a specialization of first-principles thinking applied to the option-evaluation step.
• synthesis-code-planning — Multi-approach evaluation for code tasks. This skill's constraint-first protocol slots in as the first step before the approach-generation step in code-planning.
• synthesis-implementation-integrity — Post-implementation verification. This skill catches shortcuts before they're built; implementation-integrity catches incomplete work after it's built. Use both.
• synthesis-content-quality — AI-pattern detection in prose. Different domain (prose patterns vs decision patterns) but a similar shape — both maintain a catalog that grows as failure modes evolve.

These skills work independently. They are stronger together. When loaded as a stack, the constraint-first protocol shapes how options are generated, the costume vocabulary scan shapes how drafts are reviewed, and implementation-integrity verifies that nothing slipped through to the build.

The Underlying Principle

The pattern this skill catches is one specific manifestation of a more general issue: an agent's trained defaults can quietly override the user's explicit instructions, in ways the agent itself does not notice. The fix is not "try harder to follow instructions." The fix is structural — make the conflict visible at the moment of drafting, so the override cannot happen silently.

The constraint-first protocol makes the user's constraints the first thing in the draft. The costume vocabulary scan makes the override detectable in the draft. The sub-agent acceptance audit makes the same checks portable across delegated work. The maintenance loop makes new failure modes part of the system as they emerge.

The reader who applies this discipline ships work that respects the constraints the user actually stated, not the ones the agent's training would have preferred.