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.

modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md

@@ -14,6 +14,7 @@ Scaffold a new skill directory with a `SKILL.md` and optional helper scripts und
 ### 1. Gather Requirements
 
 Ask the user:
+
 - **What does the skill do?** (trigger conditions, purpose)
 - **Are there repeatable commands?** (if yes, these become scripts)
 
@@ -26,23 +27,27 @@ Create `skills/<skill-name>/SKILL.md` with this structure:
 ```markdown
 ---
 name: <skill-name>
-description: '<One-liner: what it does and when to trigger. Keep under ~200 chars.>'
+description: "<One-liner: what it does and when to trigger. Keep under ~200 chars.>"
 ---
 
 # <Skill Title>
 
 ## Overview
+
 [1-2 sentences on purpose and scope]
 
 ## Workflow
+
 [Numbered steps the agent follows]
 ```
 
 **Guidelines:**
+
 - **Be concise.** Skills are injected into agent context — every line costs tokens. Aim for the minimum needed to reliably guide the agent.
 - **Use scripts for repeatable logic.** If a step involves a multi-line shell command, `jq` pipeline, or API call that won't change between runs, put it in a `.sh` file next to `SKILL.md` and reference it from the workflow. See `address-gh-review/` for an example.
 - **Frontmatter is required.** `name` and `description` fields. The description is what the agent uses to decide whether to load the skill, so make it specific about trigger conditions.
 - **Don't over-specify.** Trust the agent to fill gaps. Document the _what_ and _when_, not every micro-step.
+- **Split workflow from reference when the reference surface grows.** If a skill accumulates lookup tables, mapping rules, or capability references that the workflow consults, move them into a sibling `<skill>/<category>/` directory (e.g. `mappings/`, `references/`) with one sub-doc per category and an index `README.md`. Keep `SKILL.md` focused on the hot path — workflow, hard rules, and a short table pointing at the sub-docs. Include a brief style guide in the index README covering (a) defer to authoritative sources (stubs, schemas, generated docs) whenever possible, (b) row/entry formatting conventions, (c) when to create a new sub-doc vs. extend an existing one.
 
 ### 3. Present for Review