least-astonishment

Estrellas3

Forks1

Actualizado23 de julio de 2026 a las 22:15

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

Instalación

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Fuente

ilude

ilude/dotfiles

Abrir repositorio de GitHub Ver repositorios del creador

Descarga

Ocupaciones relacionadasSOC

Basado en la clasificación ocupacional SOC

Desarrolladores de softwareOcupaciones informáticas y matemáticas·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.

Más de este repositorio

mismo repositorio

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.