# Anti-Rationalization Standard

**Keywords:** skill-authoring, validation, agent-discipline, rationalizations, backfill

## Overview

Make `## Rationalizations to Reject` a required section in every user-facing harness skill, standardized as a domain-specific table format. Three universal rationalizations are defined once in the skill authoring spec. Each skill carries 3-8 domain-specific entries generated by AI and reviewed by a human. Validation enforces presence as a hard error.

### Goals

1. Prevent agents from skipping skill steps with plausible-sounding excuses
2. Standardize the format across all skills (table, domain-specific only)
3. Enforce via validation so the standard cannot drift

### Non-Goals

- Changing skill behavior or process sections
- Exempting internal/dependency-only skills — agents can rationalize skipping steps in internal skills too, so all skills require the section
- Runtime rationalization detection (this is a static spec standard)

## Decisions

### D1: Section name — `## Rationalizations to Reject`

More directive than "Common Rationalizations" (ADR original). Matches the 4 existing skills. Agents respond better to action-oriented framing.

### D2: Table format over bulleted list

`| Rationalization | Reality |` is more scannable and easier for agents to pattern-match than prose bullets. The 4 existing skills will be migrated from their current bulleted format.

### D3: Universal rationalizations defined once

Three universal entries are documented in the skill authoring spec as always-applicable. Individual skills do not repeat them — their tables contain only domain-specific entries.

Universal rationalizations (defined in `harness-skill-authoring`):

| Rationalization         | Reality                                                                     |
| ----------------------- | --------------------------------------------------------------------------- |
| "It's probably fine"    | "Probably" is not evidence. Verify before asserting.                        |
| "This is best practice" | Best practice in what context? Cite the source and confirm it applies here. |
| "We can fix it later"   | If worth flagging, document now with a concrete follow-up plan.             |

### D4: Hard error validation

`harness validate` fails if a user-facing skill is missing `## Rationalizations to Reject`. Backfill completes before enforcement ships, so no broken window.

### D5: AI-generated with human batch review

Rationalizations are generated by reading each skill's SKILL.md context, presented as a reviewable batch, then written after approval.

## Technical Design

### Files Modified

#### 1. Skill authoring spec (`agents/skills/claude-code/harness-skill-authoring/SKILL.md`)

- Add `## Rationalizations to Reject` to the required sections list
- Document the three universal rationalizations (defined once, always apply)
- Document the format contract: table, 3-8 domain-specific entries, no generic filler

#### 2. Validation (`packages/cli/src/commands/skill/validate.ts`)

- Add `'## Rationalizations to Reject'` to `REQUIRED_SECTIONS` array
- This applies to all skills; no exemption for internal skills — validate.ts does not read the `internal` flag for section validation

#### 3. Skill template (`packages/cli/src/commands/create-skill.ts`)

- Add a placeholder `## Rationalizations to Reject` section to the generated SKILL.md template with an empty table and a TODO comment

#### 4. Existing 12 skills with rationalizations

Skills across both `agents/skills/claude-code/` and `agents/commands/codex/harness/` that already have `## Rationalizations to Reject` (enforce-architecture, architecture-advisor, code-review, security-scan, api-design, auth, database, deployment):

- Migrate from bulleted Universal/Domain-Specific format to flat domain-specific table
- Remove the 3 universal entries (now in authoring spec)
- Reformat remaining domain-specific entries as `| Rationalization | Reality |` rows

#### 5. Remaining ~100 user-facing skill SKILL.md files

- Add `## Rationalizations to Reject` section with 3-5 domain-specific table entries each
- Located across `agents/skills/claude-code/` (81 files) and `agents/commands/codex/harness/` (31 files)
- All skills require the section — no exemption for internal skills

### What Is NOT Changing

- No changes to skill.yaml schema (no new fields)
- No changes to skill runtime behavior
- No changes to MCP tools
- No changes to the structure test suite beyond what validation already covers

## Success Criteria

1. `harness-skill-authoring` SKILL.md lists `## Rationalizations to Reject` as a required section with format contract and universal rationalizations defined
2. `packages/cli/src/commands/skill/validate.ts` includes `## Rationalizations to Reject` in `REQUIRED_SECTIONS`
3. `packages/cli/src/commands/create-skill.ts` template generates the section with placeholder table
4. All 12 existing skills migrated from bulleted list to table format with universal entries removed
5. All remaining ~100 skill SKILL.md files have `## Rationalizations to Reject` with 3-8 domain-specific table entries (no exemptions)
6. Every entry is specific to its skill's domain — no generic filler, no duplicated universal entries
7. `harness validate` passes across all skills after changes
8. `harness validate` fails if `## Rationalizations to Reject` is removed from any user-facing skill

## Implementation Order

1. **Spec & validation updates** — Update skill authoring spec, add to REQUIRED_SECTIONS, update create-skill template
2. **Migrate existing 12 skills** — Reformat to table, remove universal entries
3. **Generate rationalizations for ~100 skills** — AI reads each SKILL.md, generates domain-specific entries, presents full batch for human review
4. **Write approved rationalizations** — Apply reviewed entries to all ~100 skills
5. **Validate** — Run `harness validate` across all skills, confirm hard error works
