least-astonishment

Étoiles3

Forks1

Mis à jour23 juillet 2026 à 22:15

Focused, pattern-matching edits to existing code. Not for architecture strategy or pure git operations.

Installation

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Source

ilude

ilude/dotfiles

Ouvrir le dépôt GitHub Voir les dépôts du créateur

Téléchargement

Métiers associésSOC

Basé sur la classification professionnelle SOC

Développeurs de logicielsProfessions informatiques et mathématiques·SOC 15-1252

SKILL.md

readonly

name	least-astonishment
description	Focused, pattern-matching edits to existing code. Not for architecture strategy or pure git operations.

Principle of Least Astonishment

Boundary

Use this skill as an edit-time diff guard. pi/AGENTS.md Development Philosophy owns broader implementation strategy and architecture trade-offs.

Core Principle

A change should be predictable to someone who knows the codebase. If it would surprise them, make a smaller change or explain the tradeoff first.

Surprise Check

Before editing, ask:

Does this match neighboring naming, structure, error handling, and test style?
Is every changed file needed for the request?
Did I avoid drive-by formatting and unrelated cleanup?
Does any API behavior or default silently change?
Would the diff title accurately describe all touched files?
If the request requires behavior preservation during a migration or refactor, does the new path preserve that behavior until cutover?

Compliant Patterns

Fix only the requested behavior.
Match existing vocabulary and abstractions.
Preserve return types and defaults unless asked.
Add backward-compatible parameters where possible.
When a migration or refactor must preserve behavior, check that behavior before removing the old path.
Flag broader refactors separately instead of bundling them.

Anti-Patterns

Opportunistic renames or formatting.
Replacing local idioms with personal preference.
Adding a dependency for a solved local pattern.
Changing error-handling style mid-file.
Modifying cross-file callers without a clear need.

Plus depuis ce dépôt

même dépôt

pi-extension

ilude/dotfiles

Pi extensions and tool policy: extensions/*.ts, hooks, registerTool, promptGuidelines, registerCommand, footer/status UI, tool_result, session hooks, or subprocesses. Not for slash-command placement; use pi-command.

2026-08-023

docs

ilude/dotfiles

README, CHANGELOG, docs/, RFCs, ADRs, guides, or Markdown structure. Not for prose cleanup or archival work.

2026-07-273

no-ai-slop

ilude/dotfiles

Prose cleanup for filler, hype, vague claims, repetition, detection tells, or uncited specifics. Not for Markdown architecture or archival work.

2026-07-273

planning

ilude/dotfiles

Requirements, user stories, acceptance/verification criteria, or testable outcomes. Not for PRD drafting (/prd) or Pi /goal prompts.

2026-07-273

prd

ilude/dotfiles

Use for /prd-it or to draft, refine, or review a Product Requirements Document. Not for acceptance criteria, planning, or Pi /goal prompts.

2026-07-273

pi-log-analytics

ilude/dotfiles

Pi session, trace, metrics, routing, workflow-friction, workflow-telemetry, usage, or local JSONL analysis with DuckDB. Use for aggregating or correlating Pi runtime logs. Not for adding telemetry, generic SQL/database design, or non-Pi logs.

2026-07-273

name	least-astonishment
description	Focused, pattern-matching edits to existing code. Not for architecture strategy or pure git operations.

Principle of Least Astonishment

Boundary

Use this skill as an edit-time diff guard. pi/AGENTS.md Development Philosophy owns broader implementation strategy and architecture trade-offs.

Core Principle

A change should be predictable to someone who knows the codebase. If it would surprise them, make a smaller change or explain the tradeoff first.

Surprise Check

Before editing, ask:

Does this match neighboring naming, structure, error handling, and test style?
Is every changed file needed for the request?
Did I avoid drive-by formatting and unrelated cleanup?
Does any API behavior or default silently change?
Would the diff title accurately describe all touched files?
If the request requires behavior preservation during a migration or refactor, does the new path preserve that behavior until cutover?

Compliant Patterns

Fix only the requested behavior.
Match existing vocabulary and abstractions.
Preserve return types and defaults unless asked.
Add backward-compatible parameters where possible.
When a migration or refactor must preserve behavior, check that behavior before removing the old path.
Flag broader refactors separately instead of bundling them.

Anti-Patterns

Opportunistic renames or formatting.
Replacing local idioms with personal preference.
Adding a dependency for a solved local pattern.
Changing error-handling style mid-file.
Modifying cross-file callers without a clear need.