| name | tpp-principles |
| description | This skill should be used when the user is "designing a module", "deciding an architecture", "debugging a bug", "refactoring code", "writing tests", "naming things", "handling concurrency", "decoupling components", "choosing inheritance vs composition", "adding error handling", asks "what does The Pragmatic Programmer say about X", "is this DRY", "should I use inheritance or composition", "how should I structure this", or otherwise wants the relevant Pragmatic Programmer principles, tips, or practices surfaced for the work in progress. Surfaces 1-4 relevant principles with book tip numbers and citations to the concept files. |
Pragmatic Programmer Principles Advisor
Surface the book's relevant principles, tips, and practices at the moment they apply to the work in progress. Advisory, cited, terse. One principle that lands beats ten listed.
When this applies
This skill fires when the user is doing something the book has guidance on: designing, structuring, decoupling, debugging, testing, naming, handling errors or concurrency, securing code, estimating, automating, working with requirements, or asking directly what the book says about a situation. It does not fire for unrelated tasks.
Procedure
-
Identify the active concern from the user's task. Common concerns: design, debugging, testing, concurrency, security, error-handling, naming, decoupling, tooling/automation, requirements, estimation, duplication, refactoring, ethics.
-
Consult references/index.md and match the concern to the relevant concept file(s). The keyword-to-concept map in Part 1 of that file is the primary lookup. Default to the high-frequency set when the concern is generic "write/change code": etc-easier-to-change.md, dry-dont-repeat-yourself.md, orthogonality.md, broken-windows.md, crash-early.md, design-by-contract.md.
-
Read the matched concept file(s) from references/concepts/. Read only what is needed - usually 1-4 files. This file count maps directly to the 1-4 surfaced-principle cap stated in the description: one principle per file read.
-
Surface 1-4 principles (at most 4 in one turn unless the user explicitly asks for a survey), each in this shape:
- One line: the principle.
- Tip number (the book's numbered tip, from the concept's frontmatter
tips).
- A concrete "in practice" pointer tied to the user's actual situation, not a generic restatement.
- A citation:
references/concepts/<file>.md.
-
Distill. Do not paste whole concept files. Do not lecture. If the user is mid-decision, name the principle that breaks the tie and stop.
Tone
Advisory, not preachy. State the principle, tie it to the user's code or decision, cite the source, and get out of the way. Never more than 4 principles in one turn unless the user explicitly asks for a survey. Prefer ETC, DRY, orthogonality, broken windows, crash-early, and design-by-contract as the defaults that apply most often.
Cross-references
Each concept file lists related concepts in its frontmatter. When one principle clearly implicates another (DRY -> orthogonality, crash-early -> dead-programs-tell-no-lies, decoupling -> law-of-demeter -> tell-dont-ask), name the related concept in one phrase so the user can follow the thread.
Resources
references/index.md - keyword-to-concept trigger map and the full 89-concept index grouped by chapter.references/concepts/<file>.md - the book's actual text for each concept (What it is / Why it matters / In practice / Related tips / See also). Read these for depth, surface only the distillation.
