aw-ecc 1.4.21

package/skills/skill-quality-review/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: skill-quality-review
+description: Reviews skills for correctness, clarity, effectiveness, and maintainability. Use when auditing a new or updated skill, reviewing a skill PR, or troubleshooting an underperforming skill before shipping it.
+origin: ECC
+---
+
+# Skill Quality Review
+
+## Overview
+
+`skill-quality-review` is the focused reviewer lens for one skill or one small batch of closely related skill changes.
+It turns vague "this skill feels off" feedback into evidence-backed findings and small, actionable fixes.
+
+Use `skill-stocktake` for full inventory audits across many skills.
+That command may call this skill for its per-skill evaluation rubric.
+
+## When to Use
+
+- a new skill is being added and should be reviewed before merge
+- an existing skill was updated and the PR needs structured feedback
+- a skill feels ambiguous, inconsistent, or underperforming in practice
+- `skill-stocktake` flagged a skill as `Improve`, `Update`, `Retire`, or `Merge`
+- you want a reusable rubric instead of ad hoc taste-based comments
+
+Do not use this as a full repo inventory workflow.
+For broad catalog audits, use `skill-stocktake`.
+
+## Workflow
+
+1. Establish scope and the promised behavior.
+   Read the target `SKILL.md`, the diff if this is a PR, and only the bundled scripts or references that materially affect the review.
+   Restate the skill's promise from its `name`, `description`, trigger language, and body.
+2. Review correctness first.
+   Confirm commands, tool names, file paths, relative references, and workflow order are internally consistent.
+   For unstable external details such as marketplace installs, CLI flags, or API names, verify them with current sources before approving the skill.
+3. Review clarity.
+   Check that entry conditions, scope boundaries, stop conditions, and output expectations are explicit.
+   Prefer concise wording and progressive disclosure over long, duplicated explanation.
+4. Review effectiveness.
+   Ask whether a cold agent would reliably do the right thing after loading this skill.
+   The workflow should make the next action obvious, avoid hidden prerequisites, and provide enough structure for fragile steps without over-constraining flexible work.
+5. Review maintainability.
+   Look for overlap with other skills, duplicated baseline policy, stale specifics, oversized bodies, fragile references, or bundled detail that should move into a reference file.
+6. Use the detailed rubric when needed.
+   Load `references/review-rubric.md` for the full checklist, anti-pattern list, and verdict guidance.
+7. Produce findings and the smallest useful verdict.
+   For a focused review, classify blocking findings separately from advisory improvements.
+   For portfolio decisions, use `Keep`, `Improve`, `Update`, `Retire`, or `Merge into <skill>`.
+8. Recommend the smallest corrective action.
+   Prefer targeted edits, moved reference material, trimmed duplication, or explicit verification wording over broad rewrites.
+
+## Review Priorities
+
+Review in this order:
+
+1. correctness
+2. clarity
+3. effectiveness
+4. maintainability
+
+If correctness is broken, do not spend time polishing prose first.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The skill sounds right, so it is probably fine." | Skill quality depends on whether the instructions can actually be followed. |
+| "This section is long, but extra detail cannot hurt." | Bloated skills reduce trigger precision and make the workflow harder to follow. |
+| "The command probably still works." | Unverified installs, CLI flags, and external tools are correctness issues. |
+| "We can merge it and improve later." | Weak skills create bad behavior at load time, so review should happen before shipping. |
+
+## Red Flags
+
+- name, description, and body promise different things
+- the workflow hides prerequisites or assumes unstated context
+- examples, commands, or links are stale or unverifiable
+- the body duplicates baseline rules or another skill with no clear added value
+- the skill tries to cover portfolio audit, creation, and execution all at once
+- the output shape is implicit, so reviewers cannot tell what "good" looks like
+
+## Verification
+
+Before leaving the review, confirm:
+
+- [ ] the skill's promise was restated and checked against the body
+- [ ] correctness issues were reviewed before style or wording improvements
+- [ ] unstable external details were verified or explicitly flagged as unverified
+- [ ] overlap with existing skills, rules, or baseline docs was considered
+- [ ] blockers and advisories are separated clearly
+- [ ] the recommended fixes are smaller than a rewrite unless a rewrite is truly necessary
+
+## Final Output Shape
+
+Always end with:
+
+- `Mode`
+- `Scope`
+- `Skill Promise`
+- `Blocking Findings`
+- `Advisory Improvements`
+- `Verdict`
+- `Next`

package/skills/skill-quality-review/references/review-rubric.md

@@ -0,0 +1,112 @@
+# Skill Quality Review Rubric
+
+Use this rubric when a review needs more than a quick sanity pass.
+
+## 1. Correctness
+
+Check whether the skill is factually and operationally correct.
+
+- `name` and `description` match the actual behavior
+- referenced files, scripts, and relative paths exist
+- commands can plausibly run in the target environment
+- tool names, CLI flags, and API names are current
+- steps do not contradict one another
+- validation guidance matches the claimed workflow
+
+Common failures:
+
+- dead file references
+- stale install commands
+- missing bundled resources
+- hidden assumptions about tools or directory layout
+
+## 2. Clarity
+
+Check whether a cold reader can understand when and how to use the skill.
+
+- trigger conditions are explicit
+- the skill says when not to use it
+- the main workflow is ordered clearly
+- output expectations are visible
+- important terms are concrete rather than vague
+- detail lives in references when it would otherwise bloat `SKILL.md`
+
+Common failures:
+
+- rambling overview sections
+- multiple unrelated goals in one skill
+- missing stop conditions
+- buried output shapes
+
+## 3. Effectiveness
+
+Check whether the skill is likely to change behavior in the intended way.
+
+- the first action after loading the skill is obvious
+- fragile or safety-critical steps are constrained enough
+- flexible tasks keep the right degree of freedom
+- examples or templates are present where ambiguity would otherwise be high
+- the skill does not require hidden knowledge from another doc to be usable
+
+Common failures:
+
+- generic advice disguised as workflow
+- no concrete ordering for multi-step tasks
+- overfitted scripts for work that needs judgment
+- under-specified steps for brittle operations
+
+## 4. Maintainability
+
+Check whether the skill can stay healthy as the catalog evolves.
+
+- baseline policy is not duplicated unnecessarily
+- overlap with existing skills is minimal and intentional
+- long detail is pushed into references or scripts
+- the body is concise enough to justify its context cost
+- external dependencies are limited and clearly named
+- verdicts can be acted on without rereading the whole skill
+
+Common failures:
+
+- copy-pasted policy from root docs
+- large monolithic `SKILL.md` files
+- hidden dependency on another skill without naming it
+- outdated product or tool specifics embedded in core workflow text
+
+## Anti-Patterns
+
+- `Promise Drift`: frontmatter says one thing, workflow does another
+- `Catalog Overlap`: two skills solve the same problem with only wording changes
+- `Reference Rot`: links or commands look real but were never verified
+- `Context Hoarding`: long sections that belong in references or scripts
+- `Hidden Handoff`: the skill assumes another skill or doc without saying so
+- `Taste Review`: feedback describes preference, not an operational problem
+
+## Verdict Guidance
+
+| Verdict | Use when |
+|---|---|
+| `Keep` | The skill is current, distinct, and operationally sound |
+| `Improve` | The core idea is worth keeping, but wording, structure, or scope needs targeted fixes |
+| `Update` | The workflow is still useful, but references or technical details are stale |
+| `Retire` | The skill is broken, redundant, or cost-asymmetric to maintain |
+| `Merge into <skill>` | Another existing skill already owns the workflow and this one should fold into it |
+
+## Feedback Template
+
+Use this shape when the review needs a compact written summary:
+
+```text
+Mode: focused-review | portfolio-review
+Scope: <skill path or PR slice>
+Skill Promise: <one sentence>
+
+Blocking Findings:
+- <finding with evidence>
+
+Advisory Improvements:
+- <small, non-blocking improvement>
+
+Verdict: Keep | Improve | Update | Retire | Merge into <skill>
+Next: <smallest corrective action>
+```

package/skills/skill-stocktake/SKILL.md

@@ -0,0 +1,197 @@
+---
+description: "Use when auditing Claude skills and commands for quality. Supports Quick Scan (changed skills only) and Full Stocktake modes with sequential subagent batch evaluation using the shared skill-quality-review rubric."
+origin: ECC
+---
+
+# skill-stocktake
+
+Slash command (`/skill-stocktake`) that audits all Claude skills and commands using the shared `skill-quality-review` rubric plus AI holistic judgment. Supports two modes: Quick Scan for recently changed skills, and Full Stocktake for a complete review.
+
+## Scope
+
+The command targets the following paths **relative to the directory where it is invoked**:
+
+| Path | Description |
+|------|-------------|
+| `~/.claude/skills/` | Global skills (all projects) |
+| `{cwd}/.claude/skills/` | Project-level skills (if the directory exists) |
+
+**At the start of Phase 1, the command explicitly lists which paths were found and scanned.**
+
+### Targeting a specific project
+
+To include project-level skills, run from that project's root directory:
+
+```bash
+cd ~/path/to/my-project
+/skill-stocktake
+```
+
+If the project has no `.claude/skills/` directory, only global skills and commands are evaluated.
+
+## Modes
+
+| Mode | Trigger | Duration |
+|------|---------|---------|
+| Quick Scan | `results.json` exists (default) | 5–10 min |
+| Full Stocktake | `results.json` absent, or `/skill-stocktake full` | 20–30 min |
+
+**Results cache:** `~/.claude/skills/skill-stocktake/results.json`
+
+## Quick Scan Flow
+
+Re-evaluate only skills that have changed since the last run (5–10 min).
+
+1. Read `~/.claude/skills/skill-stocktake/results.json`
+2. Run: `bash ~/.claude/skills/skill-stocktake/scripts/quick-diff.sh \
+         ~/.claude/skills/skill-stocktake/results.json`
+   (Project dir is auto-detected from `$PWD/.claude/skills`; pass it explicitly only if needed)
+3. If output is `[]`: report "No changes since last run." and stop
+4. Re-evaluate only those changed files using the same Phase 2 criteria
+5. Carry forward unchanged skills from previous results
+6. Output only the diff
+7. Run: `bash ~/.claude/skills/skill-stocktake/scripts/save-results.sh \
+         ~/.claude/skills/skill-stocktake/results.json <<< "$EVAL_RESULTS"`
+
+## Full Stocktake Flow
+
+### Phase 1 — Inventory
+
+Run: `bash ~/.claude/skills/skill-stocktake/scripts/scan.sh`
+
+The script enumerates skill files, extracts frontmatter, and collects UTC mtimes.
+Project dir is auto-detected from `$PWD/.claude/skills`; pass it explicitly only if needed.
+Present the scan summary and inventory table from the script output:
+
+```
+Scanning:
+  ✓ ~/.claude/skills/         (17 files)
+  ✗ {cwd}/.claude/skills/    (not found — global skills only)
+```
+
+| Skill | 7d use | 30d use | Description |
+|-------|--------|---------|-------------|
+
+### Phase 2 — Quality Evaluation
+
+Launch an Agent tool subagent (**general-purpose agent**) with the full inventory and the shared skill-review rubric:
+
+```text
+Agent(
+  subagent_type="general-purpose",
+  prompt="
+Evaluate the following skill inventory against the rubric.
+
+Load the local `skill-quality-review` skill first and use its rubric for per-skill judgments.
+
+[INVENTORY]
+
+[RUBRIC]
+
+Return JSON for each skill:
+{ \"verdict\": \"Keep\"|\"Improve\"|\"Update\"|\"Retire\"|\"Merge into [X]\", \"reason\": \"...\" }
+"
+)
+```
+
+The subagent reads each skill, applies `skill-quality-review`, and returns per-skill JSON:
+
+`{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }`
+
+**Chunk guidance:** Process ~20 skills per subagent invocation to keep context manageable. Save intermediate results to `results.json` (`status: "in_progress"`) after each chunk.
+
+After all skills are evaluated: set `status: "completed"`, proceed to Phase 3.
+
+**Resume detection:** If `status: "in_progress"` is found on startup, resume from the first unevaluated skill.
+
+Each skill is evaluated against the `skill-quality-review` rubric:
+
+```
+- [ ] Correctness checked: commands, paths, references, and technical claims are internally valid
+- [ ] Clarity checked: trigger, scope, and output expectations are explicit
+- [ ] Effectiveness checked: a cold reader can follow the workflow without hidden prerequisites
+- [ ] Maintainability checked: overlap, duplication, and context cost are justified
+- [ ] Freshness of unstable technical references verified (use WebSearch if tool names / CLI flags / APIs are present)
+- [ ] Usage frequency considered
+```
+
+Verdict criteria:
+
+| Verdict | Meaning |
+|---------|---------|
+| Keep | Useful and current |
+| Improve | Worth keeping, but specific improvements needed |
+| Update | Referenced technology is outdated (verify with WebSearch) |
+| Retire | Low quality, stale, or cost-asymmetric |
+| Merge into [X] | Substantial overlap with another skill; name the merge target |
+
+Evaluation is **holistic AI judgment** — not a numeric rubric. Guiding dimensions:
+- **Actionability**: code examples, commands, or steps that let you act immediately
+- **Scope fit**: name, trigger, and content are aligned; not too broad or narrow
+- **Uniqueness**: value not replaceable by MEMORY.md / CLAUDE.md / another skill
+- **Currency**: technical references work in the current environment
+
+**Reason quality requirements** — the `reason` field must be self-contained and decision-enabling:
+- Do NOT write "unchanged" alone — always restate the core evidence
+- For **Retire**: state (1) what specific defect was found, (2) what covers the same need instead
+  - Bad: `"Superseded"`
+  - Good: `"disable-model-invocation: true already set; superseded by continuous-learning-v2 which covers all the same patterns plus confidence scoring. No unique content remains."`
+- For **Merge**: name the target and describe what content to integrate
+  - Bad: `"Overlaps with X"`
+  - Good: `"42-line thin content; Step 4 of chatlog-to-article already covers the same workflow. Integrate the 'article angle' tip as a note in that skill."`
+- For **Improve**: describe the specific change needed (what section, what action, target size if relevant)
+  - Bad: `"Too long"`
+  - Good: `"276 lines; Section 'Framework Comparison' (L80–140) duplicates ai-era-architecture-principles; delete it to reach ~150 lines."`
+- For **Keep** (mtime-only change in Quick Scan): restate the original verdict rationale, do not write "unchanged"
+  - Bad: `"Unchanged"`
+  - Good: `"mtime updated but content unchanged. Unique Python reference explicitly imported by rules/python/; no overlap found."`
+
+### Phase 3 — Summary Table
+
+| Skill | 7d use | Verdict | Reason |
+|-------|--------|---------|--------|
+
+### Phase 4 — Consolidation
+
+1. **Retire / Merge**: present detailed justification per file before confirming with user:
+   - What specific problem was found (overlap, staleness, broken references, etc.)
+   - What alternative covers the same functionality (for Retire: which existing skill/rule; for Merge: the target file and what content to integrate)
+   - Impact of removal (any dependent skills, MEMORY.md references, or workflows affected)
+2. **Improve**: present specific improvement suggestions with rationale:
+   - What to change and why (e.g., "trim 430→200 lines because sections X/Y duplicate python-patterns")
+   - User decides whether to act
+3. **Update**: present updated content with sources checked
+4. Check MEMORY.md line count; propose compression if >100 lines
+
+## Results File Schema
+
+`~/.claude/skills/skill-stocktake/results.json`:
+
+**`evaluated_at`**: Must be set to the actual UTC time of evaluation completion.
+Obtain via Bash: `date -u +%Y-%m-%dT%H:%M:%SZ`. Never use a date-only approximation like `T00:00:00Z`.
+
+```json
+{
+  "evaluated_at": "2026-02-21T10:00:00Z",
+  "mode": "full",
+  "batch_progress": {
+    "total": 80,
+    "evaluated": 80,
+    "status": "completed"
+  },
+  "skills": {
+    "skill-name": {
+      "path": "~/.claude/skills/skill-name/SKILL.md",
+      "verdict": "Keep",
+      "reason": "Concrete, actionable, unique value for X workflow",
+      "mtime": "2026-01-15T08:30:00Z"
+    }
+  }
+}
+```
+
+## Notes
+
+- Evaluation is blind: the same rubric applies to all skills regardless of origin (ECC, self-authored, auto-extracted)
+- Archive / delete operations always require explicit user confirmation
+- No verdict branching by skill origin

package/skills/skill-stocktake/scripts/quick-diff.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# quick-diff.sh — compare skill file mtimes against results.json evaluated_at
+# Usage: quick-diff.sh RESULTS_JSON [CWD_SKILLS_DIR]
+# Output: JSON array of changed/new files to stdout (empty [] if no changes)
+#
+# When CWD_SKILLS_DIR is omitted, defaults to $PWD/.claude/skills so the
+# script always picks up project-level skills without relying on the caller.
+#
+# Environment:
+#   SKILL_STOCKTAKE_GLOBAL_DIR   Override ~/.claude/skills (for testing only;
+#                                do not set in production — intended for bats tests)
+#   SKILL_STOCKTAKE_PROJECT_DIR  Override project dir detection (for testing only)
+
+set -euo pipefail
+
+RESULTS_JSON="${1:-}"
+CWD_SKILLS_DIR="${SKILL_STOCKTAKE_PROJECT_DIR:-${2:-$PWD/.claude/skills}}"
+GLOBAL_DIR="${SKILL_STOCKTAKE_GLOBAL_DIR:-$HOME/.claude/skills}"
+
+if [[ -z "$RESULTS_JSON" || ! -f "$RESULTS_JSON" ]]; then
+  echo "Error: RESULTS_JSON not found: ${RESULTS_JSON:-<empty>}" >&2
+  exit 1
+fi
+
+# Validate CWD_SKILLS_DIR looks like a .claude/skills path (defense-in-depth).
+# Only warn when the path exists — a nonexistent path poses no traversal risk.
+if [[ -n "$CWD_SKILLS_DIR" && -d "$CWD_SKILLS_DIR" && "$CWD_SKILLS_DIR" != */.claude/skills* ]]; then
+  echo "Warning: CWD_SKILLS_DIR does not look like a .claude/skills path: $CWD_SKILLS_DIR" >&2
+fi
+
+evaluated_at=$(jq -r '.evaluated_at' "$RESULTS_JSON")
+
+# Fail fast on a missing or malformed evaluated_at rather than producing
+# unpredictable results from ISO 8601 string comparison against "null".
+if [[ ! "$evaluated_at" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]]; then
+  echo "Error: invalid or missing evaluated_at in $RESULTS_JSON: $evaluated_at" >&2
+  exit 1
+fi
+
+# Pre-extract known paths from results.json once (O(1) lookup per file instead of O(n*m))
+known_paths=$(jq -r '.skills[].path' "$RESULTS_JSON" 2>/dev/null)
+
+tmpdir=$(mktemp -d)
+# Use a function to avoid embedding $tmpdir in a quoted string (prevents injection
+# if TMPDIR were crafted to contain shell metacharacters).
+_cleanup() { rm -rf "$tmpdir"; }
+trap _cleanup EXIT
+
+# Shared counter across process_dir calls — intentionally NOT local
+i=0
+
+process_dir() {
+  local dir="$1"
+  while IFS= read -r file; do
+    local mtime dp is_new
+    mtime=$(date -u -r "$file" +%Y-%m-%dT%H:%M:%SZ)
+    dp="${file/#$HOME/~}"
+
+    # Check if this file is known to results.json (exact whole-line match to
+    # avoid substring false-positives, e.g. "python-patterns" matching "python-patterns-v2").
+    if echo "$known_paths" | grep -qxF "$dp"; then
+      is_new="false"
+      # Known file: only emit if mtime changed (ISO 8601 string comparison is safe)
+      [[ "$mtime" > "$evaluated_at" ]] || continue
+    else
+      is_new="true"
+      # New file: always emit regardless of mtime
+    fi
+
+    jq -n \
+      --arg path "$dp" \
+      --arg mtime "$mtime" \
+      --argjson is_new "$is_new" \
+      '{path:$path,mtime:$mtime,is_new:$is_new}' \
+      > "$tmpdir/$i.json"
+    i=$((i+1))
+  done < <(find "$dir" -name "*.md" -type f 2>/dev/null | sort)
+}
+
+[[ -d "$GLOBAL_DIR" ]] && process_dir "$GLOBAL_DIR"
+[[ -n "$CWD_SKILLS_DIR" && -d "$CWD_SKILLS_DIR" ]] && process_dir "$CWD_SKILLS_DIR"
+
+if [[ $i -eq 0 ]]; then
+  echo "[]"
+else
+  jq -s '.' "$tmpdir"/*.json
+fi

package/skills/skill-stocktake/scripts/save-results.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# save-results.sh — merge evaluated skills into results.json with correct UTC timestamp
+# Usage: save-results.sh RESULTS_JSON <<< "$EVAL_JSON"
+#
+# stdin format:
+#   { "skills": {...}, "mode"?: "full"|"quick", "batch_progress"?: {...} }
+#
+# Always sets evaluated_at to current UTC time via `date -u`.
+# Merges stdin .skills into existing results.json (new entries override old).
+# Optionally updates .mode and .batch_progress if present in stdin.
+
+set -euo pipefail
+
+RESULTS_JSON="${1:-}"
+
+if [[ -z "$RESULTS_JSON" ]]; then
+  echo "Error: RESULTS_JSON argument required" >&2
+  echo "Usage: save-results.sh RESULTS_JSON <<< \"\$EVAL_JSON\"" >&2
+  exit 1
+fi
+
+EVALUATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Read eval results from stdin and validate JSON before touching the results file
+input_json=$(cat)
+if ! echo "$input_json" | jq empty 2>/dev/null; then
+  echo "Error: stdin is not valid JSON" >&2
+  exit 1
+fi
+
+if [[ ! -f "$RESULTS_JSON" ]]; then
+  # Bootstrap: create new results.json from stdin JSON + current UTC timestamp
+  echo "$input_json" | jq --arg ea "$EVALUATED_AT" \
+    '. + { evaluated_at: $ea }' > "$RESULTS_JSON"
+  exit 0
+fi
+
+# Merge: new .skills override existing ones; old skills not in input_json are kept.
+# Optionally update .mode and .batch_progress if provided.
+#
+# Use mktemp for a collision-safe temp file (concurrent runs on the same RESULTS_JSON
+# would race on a predictable ".tmp" suffix; random suffix prevents silent overwrites).
+tmp=$(mktemp "${RESULTS_JSON}.XXXXXX")
+trap 'rm -f "$tmp"' EXIT
+
+jq -s \
+  --arg ea "$EVALUATED_AT" \
+  '.[0] as $existing | .[1] as $new |
+   $existing |
+   .evaluated_at = $ea |
+   .skills = ($existing.skills + ($new.skills // {})) |
+   if ($new | has("mode")) then .mode = $new.mode else . end |
+   if ($new | has("batch_progress")) then .batch_progress = $new.batch_progress else . end' \
+  "$RESULTS_JSON" <(echo "$input_json") > "$tmp"
+
+mv "$tmp" "$RESULTS_JSON"