docs(pi/agents): expand principles and comment style guidance

Add explicit priority order (correctness > maintainability > polish),
tighten comment style to default-no-comment with why-only rationale,
and document splitting skill workflow from reference sub-docs.

modules/home/programs/terminal/pi/config/AGENTS.md

@@ -29,26 +29,33 @@ Full-file reads are fine when genuinely needed, but avoid them as the default re
 
 ## Principles
 
-1. **KISS / YAGNI**: Keep solutions simple. Avoid abstractions, generics, or indirection unless there is a concrete need.
+1. **Priority order**: When goals conflict, optimize in this order:
+   1. **Correctness** — solve the actual use case, including the realistic failure modes (not just the happy path).
+   2. **Maintainability / readability** — non-negotiable. Code is read far more than it is written; clarity wins over cleverness.
+   3. **Abstraction & polish** — only after the above are solid, and only when a concrete need justifies it.
 
-2. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.
+   All three matter, but never sacrifice (2) for (3). Prefer obvious, boring code over slick code that requires a paragraph to explain.
 
-3. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful.
+2. **KISS / YAGNI**: Avoid abstractions, generics, or indirection unless there is a concrete, present need. Speculative flexibility is a maintainability tax.
+
+3. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.
+
+4. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful.
 
 ## Style
 
 ### Comment Style
 
-A logical block of code (not necessarily a language scope) should have a short Title Case comment above it:
+Default to **no comment**. Code should be self-explanatory through naming and structure. Only add a comment when it earns its place by explaining something the code cannot.
 
-```go
-// Map Component Results
-for _, comp := range components {
-    results[comp.Name] = comp.Result
-}
-```
+Write a comment when, and only when:
 
-If the block is more complicated or non-obvious, explain _why_ after the title:
+1. The _why_ is non-obvious (intent, constraint, workaround, surprising invariant).
+2. A reader familiar with the language/codebase would otherwise stop and ask "why?".
+
+Do not narrate _what_ the code does. Do not add Title Case section headers over logical blocks just to label them.
+
+When a comment _is_ warranted, use a short Title Case label, a dash, and the _why_:
 
 ```go
 // Map Component Results - Downstream consumers expect a name-keyed lookup.
@@ -56,3 +63,11 @@ for _, comp := range components {
     results[comp.Name] = comp.Result
 }
 ```
+
+Rules for the explanation after the dash:
+
+- Keep it to **2–3 sentences max**. Never a paragraph.
+- State the _why_ directly. Do not restate what the code does, recap prior context, or hedge.
+- Do **not** hard-wrap comments at 80 columns. Up to ~120 is fine.
+
+If a block is complex enough that it needs a heading just to be navigable, that is usually a signal to extract a well-named function instead.