@ngockhoale/ukit 1.6.8 → 2.0.2

package/templates/.claude/skills/pptx/utilities.md

@@ -0,0 +1,62 @@
+# PPTX Utility Commands
+
+Reference commands for thumbnail generation and slide-to-image conversion. Not part of the core create/edit workflows.
+
+## Creating Thumbnail Grids
+
+To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:
+
+```bash
+python scripts/thumbnail.py template.pptx [output_prefix]
+```
+
+**Features**:
+- Creates: `thumbnails.jpg` (or `thumbnails-1.jpg`, `thumbnails-2.jpg`, etc. for large decks)
+- Default: 5 columns, max 30 slides per grid (5×6)
+- Custom prefix: `python scripts/thumbnail.py template.pptx my-grid`
+  - Note: The output prefix should include the path if you want output in a specific directory (e.g., `workspace/my-grid`)
+- Adjust columns: `--cols 4` (range: 3-6, affects slides per grid)
+- Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
+- Slides are zero-indexed (Slide 0, Slide 1, etc.)
+
+**Use cases**:
+- Template analysis: Quickly understand slide layouts and design patterns
+- Content review: Visual overview of entire presentation
+- Navigation reference: Find specific slides by their visual appearance
+- Quality check: Verify all slides are properly formatted
+
+**Examples**:
+```bash
+# Basic usage
+python scripts/thumbnail.py presentation.pptx
+
+# Combine options: custom name, columns
+python scripts/thumbnail.py template.pptx analysis --cols 4
+```
+
+## Converting Slides to Images
+
+To visually analyze PowerPoint slides, convert them to images using a two-step process:
+
+1. **Convert PPTX to PDF**:
+   ```bash
+   soffice --headless --convert-to pdf template.pptx
+   ```
+
+2. **Convert PDF pages to JPEG images**:
+   ```bash
+   pdftoppm -jpeg -r 150 template.pdf slide
+   ```
+   This creates files like `slide-1.jpg`, `slide-2.jpg`, etc.
+
+Options:
+- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)
+- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)
+- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)
+- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)
+- `slide`: Prefix for output files
+
+Example for specific range:
+```bash
+pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5
+```

package/templates/.claude/skills/project-learning/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: project-learning
+description: Use after completing non-trivial work in a project, when a repeated coding pattern (naming, structure, framework usage) was observed across multiple files or multiple sessions, to propose it as a project convention for human approval. Never auto-applies a convention.
+---
+
+# Project Learning
+
+Detecting a project's own conventions is a judgment call, not something a deterministic script can do — it needs a live agent reading real code. This skill turns that judgment into a proposal, never a silent change.
+
+## When to use
+
+After finishing a task, if either is true:
+
+- The same non-obvious pattern was seen in 2+ places in existing code you read (e.g. every form field uses `ControlInput`, never a raw `<input>`).
+- The human corrected your output in a way that would recur (e.g. you wrote `form`, they renamed it to `workingObj` — this is exactly Example 3 in the maintainer's own global `CLAUDE.md` Surgical Changes section).
+
+One-off patterns are not conventions. Skip this for anything seen only once.
+
+## What NOT to do
+
+Never write directly into `conventions`, and never mention this to the human as if it's already decided. Always propose through Task 10's storage path — call `proposePatternCandidate(projectRoot, projectId, candidate)` from `src/core/memory/store.js` (or, from a plain conversation, tell the human to check `ukit memory list --pending`). Phrase the candidate as one falsifiable sentence:
+
+- Good: "Use `ControlInput` from `src/components/` instead of raw `<input>` for form fields."
+- Bad: "This project seems to like custom inputs."
+
+## Human approval loop
+
+The human reviews pending candidates with `ukit memory list --pending` and decides with `ukit memory approve <id>` or `ukit memory reject <id>`. Until approved, a candidate has zero effect on any future session — no session reads a `pending` candidate as if it were an established convention.
+
+## Scope
+
+Project-local only for v2.0. Do not write to `user.preferences`/`user.rules` (global, cross-project) — that scope is deferred to a later plan.

package/templates/.claude/skills/root-cause-tracing/SKILL.md

@@ -13,20 +13,7 @@ Bugs often manifest deep in the call stack (git init in wrong directory, file cr
 
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Bug appears deep in stack?" [shape=diamond];
-    "Can trace backwards?" [shape=diamond];
-    "Fix at symptom point" [shape=box];
-    "Trace to original trigger" [shape=box];
-    "BETTER: Also add defense-in-depth" [shape=box];
-
-    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
-    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
-    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
-    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
-}
-```
+Flow diagram: [`diagrams.md`](diagrams.md#when-to-use).
 
 **Use when:**
 - Error happens deep in execution (not at entry point)
@@ -134,27 +121,7 @@ Runs tests one-by-one, stops at first polluter. See script for usage.
 
 ## Key Principle
 
-```dot
-digraph principle {
-    "Found immediate cause" [shape=ellipse];
-    "Can trace one level up?" [shape=diamond];
-    "Trace backwards" [shape=box];
-    "Is this the source?" [shape=diamond];
-    "Fix at source" [shape=box];
-    "Add validation at each layer" [shape=box];
-    "Bug impossible" [shape=doublecircle];
-    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
-
-    "Found immediate cause" -> "Can trace one level up?";
-    "Can trace one level up?" -> "Trace backwards" [label="yes"];
-    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
-    "Trace backwards" -> "Is this the source?";
-    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
-    "Is this the source?" -> "Fix at source" [label="yes"];
-    "Fix at source" -> "Add validation at each layer";
-    "Add validation at each layer" -> "Bug impossible";
-}
-```
+Flow diagram: [`diagrams.md`](diagrams.md#key-principle).
 
 **NEVER fix just where the error appears.** Trace back to find the original trigger.
 

package/templates/.claude/skills/root-cause-tracing/diagrams.md

@@ -0,0 +1,44 @@
+# Root Cause Tracing — Flow Diagrams
+
+Graphviz restatements of the decision flow in `SKILL.md`. The prose in `SKILL.md` is the source of truth; these are visual aids for the same logic.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```

package/templates/.claude/skills/sharing-skills/SKILL.md

@@ -99,47 +99,7 @@ EOF
 )"
 ```
 
-## Complete Example
-
-Here's a complete example of sharing a skill called "async-patterns":
-
-```bash
-# 1. Sync with upstream
-cd ~/.config/superpowers/skills/
-git checkout main
-git pull upstream main
-git push origin main
-
-# 2. Create branch
-git checkout -b "add-async-patterns-skill"
-
-# 3. Create/edit the skill
-# (Work on skills/async-patterns/SKILL.md)
-
-# 4. Commit
-git add skills/async-patterns/
-git commit -m "Add async-patterns skill
-
-Patterns for handling asynchronous operations in tests and application code.
-
-Tested with: Multiple pressure scenarios testing agent compliance."
-
-# 5. Push
-git push -u origin "add-async-patterns-skill"
-
-# 6. Create PR
-gh pr create \
-  --repo upstream-org/upstream-repo \
-  --title "Add async-patterns skill" \
-  --body "## Summary
-Patterns for handling asynchronous operations correctly in tests and application code.
-
-## Testing
-Tested with multiple application scenarios. Agents successfully apply patterns to new code.
-
-## Context
-Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
-```
+Full worked example (async-patterns skill, all 6 steps filled in): [`complete-example.md`](complete-example.md).
 
 ## After PR is Merged
 

package/templates/.claude/skills/sharing-skills/complete-example.md

@@ -0,0 +1,41 @@
+# Sharing Skills — Complete Example
+
+Full walkthrough of the "Sharing Workflow" steps in `SKILL.md`, filled in for a skill called "async-patterns".
+
+```bash
+# 1. Sync with upstream
+cd ~/.config/superpowers/skills/
+git checkout main
+git pull upstream main
+git push origin main
+
+# 2. Create branch
+git checkout -b "add-async-patterns-skill"
+
+# 3. Create/edit the skill
+# (Work on skills/async-patterns/SKILL.md)
+
+# 4. Commit
+git add skills/async-patterns/
+git commit -m "Add async-patterns skill
+
+Patterns for handling asynchronous operations in tests and application code.
+
+Tested with: Multiple pressure scenarios testing agent compliance."
+
+# 5. Push
+git push -u origin "add-async-patterns-skill"
+
+# 6. Create PR
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add async-patterns skill" \
+  --body "## Summary
+Patterns for handling asynchronous operations correctly in tests and application code.
+
+## Testing
+Tested with multiple application scenarios. Agents successfully apply patterns to new code.
+
+## Context
+Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
+```

package/templates/.claude/skills/skill-quality/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: skill-quality
+description: Use when creating or editing a UKit template skill/agent (templates/.claude/skills or templates/.claude/agents), before shipping the change, to pressure-test compliance and trigger accuracy. Maintainer-only.
+---
+
+# Skill Quality
+
+Maintainer-only. Pressure-tests a skill/agent before shipping a change, the same way a unit test pressure-tests code. UKit cannot run this itself — `scripts/skill/audit-skill.mjs` only scaffolds files and records results, it never calls a model. The actual test runs inside a live Claude Code (or Codex) session, by dispatching a subagent (via `Agent`/`Task`) to follow the pressure scenario.
+
+## When to use
+
+Editing or creating a **discipline-enforcing** skill/agent — one with rules meant to hold under pressure (e.g. `systematic-debugging`, `verification-before-completion`, `executing-plans`). Skip this for pure-reference skills (`pdf`, `docx`) that have no compliance rule to break.
+
+## The loop: RED → GREEN → REFACTOR
+
+1. **RED** — dispatch a subagent with the pressure scenario but *without* the skill loaded. Record its choice and the exact rationalization it used, verbatim.
+2. **GREEN** — load the skill (new or patched), re-run the same scenario. Expect compliance. If it still fails, the skill's language is too weak — patch and re-run before moving on.
+3. **REFACTOR** — if a *new* rationalization surfaces later (different scenario, same skill), don't bolt a soft exception onto the existing rule. Add an explicit counter, a row in `rationalization-table-template.md`, and a red-flag entry, then re-test the original scenario too — a new exception must not silently loosen the old one.
+
+## Output format
+
+```
+Compliance: NN%
+Weakness found: <one line>
+Rationalization detected: "<verbatim quote>"
+Recommended patch: <one line>
+```
+
+## Trigger accuracy check
+
+Separate from compliance: does the skill's `description` frontmatter actually get it loaded at the right time? Dispatch N subagents with prompts that *should* trigger the skill and M that *should not*, giving them only the frontmatter `description` — the same information a real session uses to decide whether to load a skill. Fixture and report format: `trigger-accuracy-template.md`.
+
+## Templates
+
+- `pressure-scenario-template.md` — how to write a scenario, with a real worked example already run against `systematic-debugging`.
+- `rationalization-table-template.md` — the closing-the-loophole table + the 3 hardening techniques.
+- `trigger-accuracy-template.md` — fixture + report format for the check above.

package/templates/.claude/skills/skill-quality/pressure-scenario-template.md

@@ -0,0 +1,20 @@
+# Pressure Scenario Template
+
+## How to write a scenario
+
+- Combine **3+ pressure types** from: time, sunk-cost, authority, economic, exhaustion, social.
+- Force a concrete **A/B/C choice**, not an open question. "What do you do?" — not "what should you do?"
+- Use real file paths and real numbers, not abstractions.
+- Frame it as real: "This is a real scenario. You must choose and act. Don't ask hypothetical questions."
+- End with: "Be honest about what you would actually do."
+
+## Worked example — don't copy it here, read the original
+
+Rather than duplicating a worked scenario in this file, reuse the one already written and already run in this repo: `templates/.claude/skills/systematic-debugging/test-pressure-1.md` (economic + authority + time + sunk-cost pressure, A/B/C choice, passed against `systematic-debugging`). Open it directly, swap the skill name and domain details for the skill you're testing. See its sibling `CREATION-LOG.md` → "Bulletproofing Elements" for the language choices (ALWAYS/NEVER, explicit "even if faster") that made the original pass.
+
+## Producing your own scenario (when the worked example doesn't fit the skill's domain)
+
+1. Identify the rule the skill is meant to enforce and the shortcut an agent would be tempted to take instead.
+2. Pick 3+ pressure types that would plausibly justify the shortcut in the moment.
+3. Write the A/B/C choice so the "wrong" answer is the one that feels most reasonable under pressure — that's the point of the test.
+4. Record the subagent's raw choice and its exact reasoning, not a paraphrase.

package/templates/.claude/skills/skill-quality/rationalization-table-template.md

@@ -0,0 +1,15 @@
+# Rationalization Table Template
+
+Close a found rationalization with all three, not just one:
+
+1. **Explicit negation** — state the subagent's exact justification, then negate it directly in the skill's text. ("The deadline changes things" → "the deadline does not change this," not a vague "be careful.")
+2. **Table row** — append below. Never delete a row; a closed loophole can reopen if wording drifts later.
+3. **Red-flags entry** — add the excuse's *pattern* (not just its wording) to the skill's own "if you're thinking X, that's the shortcut talking" list, so a reworded version is still caught.
+
+| Excuse | Reality |
+|---|---|
+| *(verbatim rationalization found in RED)* | *(one-line counter-fact)* |
+
+## Gotcha
+
+Don't patch a rationalization with a soft "nuance clause" (e.g. "...unless it's genuinely urgent") appended to an otherwise-working rule — that clause becomes the next rationalization. A real exception must be its own conditional keyed to an observable predicate (a specific file pattern, a specific error type), never a general escape hatch.

package/templates/.claude/skills/skill-quality/trigger-accuracy-template.md

@@ -0,0 +1,32 @@
+# Trigger Accuracy Template
+
+Tests whether a skill's frontmatter `description` loads it at the right time — not whether its body is correct once loaded.
+
+## Fixture format
+
+```yaml
+skill: <skill-name>
+should-trigger:
+  - "prompt that clearly matches this skill's purpose"
+  - "a differently-worded prompt that should still match"
+should-not-trigger:
+  - "a prompt from an adjacent but different skill's domain"
+  - "a prompt that mentions a keyword from the description out of context"
+```
+
+At least 3 prompts per list. `should-not-trigger` prompts should be near-misses (shared keyword, wrong intent) — obviously unrelated prompts prove nothing.
+
+## Running it
+
+Per prompt, dispatch a subagent given **only** the frontmatter `description` and ask: "would you load this skill for this request? yes/no" — mirrors how a real session decides.
+
+## Report format
+
+```
+Should trigger: x/N
+Should not trigger: y/M
+False positives: <should-not-trigger prompt that fired anyway, and why>
+False negatives: <should-trigger prompt that didn't fire, and why>
+```
+
+A false negative usually means the `description` is too narrow or uses jargon the prompt wouldn't contain. A false positive usually means it's too broad or shares vocabulary with an unrelated domain — tighten with a more specific verb/noun pairing rather than adding exclusions.