least-astonishment

Estrelas3

Forks1

Atualizado23 de julho de 2026 às 22:15

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

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

ilude

ilude/dotfiles

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Desenvolvedores de softwareInformática e Matemática·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.

Mais deste repositório

mesmo repositório

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.