shmakk 1.1.0 → 1.2.0

package/skills/workflow-receiving-code-review.md

@@ -0,0 +1,214 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+category: workflow
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/skills/workflow-repo-story-time.md

@@ -0,0 +1,155 @@
+---
+name: repo-story-time
+description: 'Generate a comprehensive repository summary and narrative story from commit history'
+category: workflow
+---
+
+## Role
+
+You're a senior technical analyst and storyteller with expertise in repository archaeology, code pattern analysis, and narrative synthesis. Your mission is to transform raw repository data into compelling technical narratives that reveal the human stories behind the code.
+
+## Task
+
+Transform any repository into a comprehensive analysis with two deliverables:
+
+1. **REPOSITORY_SUMMARY.md** - Technical architecture and purpose overview
+2. **THE_STORY_OF_THIS_REPO.md** - Narrative story from commit history analysis
+
+**CRITICAL**: You must CREATE and WRITE these files with complete markdown content. Do NOT output the markdown content in the chat - use the `editFiles` tool to create the actual files in the repository root directory.
+
+## Methodology
+
+### Phase 1: Repository Exploration
+
+**EXECUTE these commands immediately** to understand the repository structure and purpose:
+
+1. Get repository overview by running:
+   `Get-ChildItem -Recurse -Include "*.md","*.json","*.yaml","*.yml" | Select-Object -First 20 | Select-Object Name, DirectoryName`
+
+2. Understand project structure by running:
+   `Get-ChildItem -Recurse -Directory | Where-Object {$_.Name -notmatch "(node_modules|\.git|bin|obj)"} | Select-Object -First 30 | Format-Table Name, FullName`
+
+After executing these commands, use semantic search to understand key concepts and technologies. Look for:
+- Configuration files (package.json, pom.xml, requirements.txt, etc.)
+- README files and documentation
+- Main source directories
+- Test directories
+- Build/deployment configurations
+
+### Phase 2: Technical Deep Dive
+Create comprehensive technical inventory:
+- **Purpose**: What problem does this repository solve?
+- **Architecture**: How is the code organized?
+- **Technologies**: What languages, frameworks, and tools are used?
+- **Key Components**: What are the main modules/services/features?
+- **Data Flow**: How does information move through the system?
+
+### Phase 3: Commit History Analysis
+
+**EXECUTE these git commands systematically** to understand repository evolution:
+
+**Step 1: Basic Statistics** - Run these commands to get repository metrics:
+- `git rev-list --all --count` (total commit count)
+- `(git log --oneline --since="1 year ago").Count` (commits in last year)
+
+**Step 2: Contributor Analysis** - Run this command:
+- `git shortlog -sn --since="1 year ago" | Select-Object -First 20`
+
+**Step 3: Activity Patterns** - Run this command:
+- `git log --since="1 year ago" --format="%ai" | ForEach-Object { $_.Substring(0,7) } | Group-Object | Sort-Object Count -Descending | Select-Object -First 12`
+
+**Step 4: Change Pattern Analysis** - Run these commands:
+- `git log --since="1 year ago" --oneline --grep="feat|fix|update|add|remove" | Select-Object -First 50`
+- `git log --since="1 year ago" --name-only --oneline | Where-Object { $_ -notmatch "^[a-f0-9]" } | Group-Object | Sort-Object Count -Descending | Select-Object -First 20`
+
+**Step 5: Collaboration Patterns** - Run this command:
+- `git log --since="1 year ago" --merges --oneline | Select-Object -First 20`
+
+**Step 6: Seasonal Analysis** - Run this command:
+- `git log --since="1 year ago" --format="%ai" | ForEach-Object { $_.Substring(5,2) } | Group-Object | Sort-Object Name`
+
+**Important**: Execute each command and analyze the output before proceeding to the next step.
+**Important**: Use your best judgment to execute additional commands not listed above based on the output of previous commands or the repository's specific content.
+
+### Phase 4: Pattern Recognition
+Look for these narrative elements:
+- **Characters**: Who are the main contributors? What are their specialties?
+- **Seasons**: Are there patterns by month/quarter? Holiday effects?
+- **Themes**: What types of changes dominate? (features, fixes, refactoring)
+- **Conflicts**: Are there areas of frequent change or contention?
+- **Evolution**: How has the repository grown and changed over time?
+
+## Output Format
+
+### REPOSITORY_SUMMARY.md Structure
+```markdown
+# Repository Analysis: [Repo Name]
+
+## Overview
+Brief description of what this repository does and why it exists.
+
+## Architecture
+High-level technical architecture and organization.
+
+## Key Components
+- **Component 1**: Description and purpose
+- **Component 2**: Description and purpose
+[Continue for all major components]
+
+## Technologies Used
+List of programming languages, frameworks, tools, and platforms.
+
+## Data Flow
+How information moves through the system.
+
+## Team and Ownership
+Who maintains different parts of the codebase.
+```
+
+### THE_STORY_OF_THIS_REPO.md Structure
+```markdown
+# The Story of [Repo Name]
+
+## The Chronicles: A Year in Numbers
+Statistical overview of the past year's activity.
+
+## Cast of Characters
+Profiles of main contributors with their specialties and impact.
+
+## Seasonal Patterns
+Monthly/quarterly analysis of development activity.
+
+## The Great Themes
+Major categories of work and their significance.
+
+## Plot Twists and Turning Points
+Notable events, major changes, or interesting patterns.
+
+## The Current Chapter
+Where the repository stands today and future implications.
+```
+
+## Key Instructions
+
+1. **Be Specific**: Use actual file names, commit messages, and contributor names
+2. **Find Stories**: Look for interesting patterns, not just statistics
+3. **Context Matters**: Explain why patterns exist (holidays, releases, incidents)
+4. **Human Element**: Focus on the people and teams behind the code
+5. **Technical Depth**: Balance narrative with technical accuracy
+6. **Evidence-Based**: Support observations with actual git data
+
+## Success Criteria
+
+- Both markdown files are **ACTUALLY CREATED** with complete, comprehensive content using the `editFiles` tool
+- **NO markdown content should be output to chat** - all content must be written directly to the files
+- Technical summary accurately represents repository architecture
+- Narrative story reveals human patterns and interesting insights
+- Git commands provide concrete evidence for all claims
+- Analysis reveals both technical and cultural aspects of development
+- Files are ready to use immediately without any copy/paste from chat dialog
+
+## Critical Final Instructions
+
+**DO NOT** output markdown content in the chat. **DO** use the `editFiles` tool to create both files with complete content. The deliverables are the actual files, not chat output.
+
+Remember: Every repository tells a story. Your job is to uncover that story through systematic analysis and present it in a way that both technical and non-technical audiences can appreciate.

package/skills/workflow-requesting-code-review.md

@@ -0,0 +1,104 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+category: workflow
+---
+
+# Requesting Code Review
+
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code reviewer subagent:**
+
+Use Task tool with `general-purpose` type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{DESCRIPTION}` - Brief summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each task or at natural checkpoints
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/skills/workflow-session-report.md

@@ -0,0 +1,43 @@
+---
+name: session-report
+description: Generate an explorable HTML report of Claude Code session usage (tokens, cache, subagents, skills, expensive prompts) from ~/.claude/projects transcripts.
+category: workflow
+---
+
+# Session Report
+
+Produce a self-contained HTML report of Claude Code usage and save it to the current working directory.
+
+## Steps
+
+1. **Get data.** Run the bundled analyzer (default window: last 7 days; honor a different range if the user passed one, e.g. `24h`, `30d`, or `all`). The script `analyze-sessions.mjs` lives in the same directory as this SKILL.md — use its absolute path:
+   ```sh
+   node <skill-dir>/analyze-sessions.mjs --json --since 7d > /tmp/session-report.json
+   ```
+   For all-time, omit `--since`.
+
+2. **Read** `/tmp/session-report.json`. Skim `overall`, `by_project`, `by_subagent_type`, `by_skill`, `cache_breaks`, `top_prompts`.
+
+3. **Copy the template** (also bundled alongside this SKILL.md) to the output path in the current working directory:
+   ```sh
+   cp <skill-dir>/template.html ./session-report-$(date +%Y%m%d-%H%M).html
+   ```
+
+4. **Edit the output file** (use Edit, not Write — preserve the template's JS/CSS):
+   - Replace the contents of `<script id="report-data" type="application/json">` with the full JSON from step 1. The page's JS renders the hero total, all tables, bars, and drill-downs from this blob automatically.
+   - Fill the `<!-- AGENT: anomalies -->` block with **3–5 one-line findings**. Express figures as a **% of total tokens** wherever possible (total = `overall.input_tokens.total + overall.output_tokens`). One line per finding, exact markup:
+     ```html
+     <div class="take bad"><div class="fig">41.2%</div><div class="txt"><b>cc-monitor</b> consumed 41% of the week across just 3 sessions</div></div>
+     ```
+     Classes: `.take bad` for waste/anomalies (red), `.take good` for healthy signals (green), `.take info` for neutral facts (blue). The `.fig` is one short number (a %, a count, or a multiplier like `12×`). The `.txt` is one plain-English sentence naming the project/skill/prompt; wrap the subject in `<b>`. Look for: a project or skill eating a disproportionate share, cache-hit <85%, a single prompt >2% of total, subagent types averaging >1M tokens/call, cache breaks clustering.
+   - Fill the `<!-- AGENT: optimizations -->` block (at the **bottom** of the page) with 1–4 `<div class="callout">` suggestions tied to specific rows (e.g. "`/weekly-status` spawned 7 subagents for 8.1% of total — scope it to fewer parallel agents").
+   - Do not restructure existing sections.
+
+5. **Report** the saved file path to the user. Do not open it or render it.
+
+## Notes
+
+- The template is the source of interactivity (sorting, expand/collapse, block-char bars). Your job is data + narrative, not markup.
+- Keep commentary terse and specific — reference actual project names, numbers, timestamps from the JSON.
+- `top_prompts` already includes subagent tokens and rolls task-notification continuations into the originating prompt.
+- If the JSON is >2MB, trim `top_prompts` to 100 entries and `cache_breaks` to 100 before embedding (they should already be capped).

package/skills/workflow-structured-autonomy-generate.md

@@ -0,0 +1,126 @@
+---
+name: structured-autonomy-generate
+description: 'Structured Autonomy Implementation Generator Prompt'
+category: workflow
+---
+
+You are a PR implementation plan generator that creates complete, copy-paste ready implementation documentation.
+
+Your SOLE responsibility is to:
+1. Accept a complete PR plan (plan.md in plans/{feature-name}/)
+2. Extract all implementation steps from the plan
+3. Generate comprehensive step documentation with complete code
+4. Save plan to: `plans/{feature-name}/implementation.md`
+
+Follow the <workflow> below to generate and save implementation files for each step in the plan.
+
+<workflow>
+
+## Step 1: Parse Plan & Research Codebase
+
+1. Read the plan.md file to extract:
+   - Feature name and branch (determines root folder: `plans/{feature-name}/`)
+   - Implementation steps (numbered 1, 2, 3, etc.)
+   - Files affected by each step
+2. Run comprehensive research ONE TIME using <research_task>. Use `runSubagent` to execute. Do NOT pause.
+3. Once research returns, proceed to Step 2 (file generation).
+
+## Step 2: Generate Implementation File
+
+Output the plan as a COMPLETE markdown document using the <plan_template>, ready to be saved as a `.md` file.
+
+The plan MUST include:
+- Complete, copy-paste ready code blocks with ZERO modifications needed
+- Exact file paths appropriate to the project structure
+- Markdown checkboxes for EVERY action item
+- Specific, observable, testable verification points
+- NO ambiguity - every instruction is concrete
+- NO "decide for yourself" moments - all decisions made based on research
+- Technology stack and dependencies explicitly stated
+- Build/test commands specific to the project type
+
+</workflow>
+
+<research_task>
+For the entire project described in the master plan, research and gather:
+
+1. **Project-Wide Analysis:**
+   - Project type, technology stack, versions
+   - Project structure and folder organization
+   - Coding conventions and naming patterns
+   - Build/test/run commands
+   - Dependency management approach
+
+2. **Code Patterns Library:**
+   - Collect all existing code patterns
+   - Document error handling patterns
+   - Record logging/debugging approaches
+   - Identify utility/helper patterns
+   - Note configuration approaches
+
+3. **Architecture Documentation:**
+   - How components interact
+   - Data flow patterns
+   - API conventions
+   - State management (if applicable)
+   - Testing strategies
+
+4. **Official Documentation:**
+   - Fetch official docs for all major libraries/frameworks
+   - Document APIs, syntax, parameters
+   - Note version-specific details
+   - Record known limitations and gotchas
+   - Identify permission/capability requirements
+
+Return a comprehensive research package covering the entire project context.
+</research_task>
+
+<plan_template>
+# {FEATURE_NAME}
+
+## Goal
+{One sentence describing exactly what this implementation accomplishes}
+
+## Prerequisites
+Make sure that the use is currently on the `{feature-name}` branch before beginning implementation.
+If not, move them to the correct branch. If the branch does not exist, create it from main.
+
+### Step-by-Step Instructions
+
+#### Step 1: {Action}
+- [ ] {Specific instruction 1}
+- [ ] Copy and paste code below into `{file}`:
+
+```{language}
+{COMPLETE, TESTED CODE - NO PLACEHOLDERS - NO "TODO" COMMENTS}
+```
+
+- [ ] {Specific instruction 2}
+- [ ] Copy and paste code below into `{file}`:
+
+```{language}
+{COMPLETE, TESTED CODE - NO PLACEHOLDERS - NO "TODO" COMMENTS}
+```
+
+##### Step 1 Verification Checklist
+- [ ] No build errors
+- [ ] Specific instructions for UI verification (if applicable)
+
+#### Step 1 STOP & COMMIT
+**STOP & COMMIT:** Agent must stop here and wait for the user to test, stage, and commit the change.
+
+#### Step 2: {Action}
+- [ ] {Specific Instruction 1}
+- [ ] Copy and paste code below into `{file}`:
+
+```{language}
+{COMPLETE, TESTED CODE - NO PLACEHOLDERS - NO "TODO" COMMENTS}
+```
+
+##### Step 2 Verification Checklist
+- [ ] No build errors
+- [ ] Specific instructions for UI verification (if applicable)
+
+#### Step 2 STOP & COMMIT
+**STOP & COMMIT:** Agent must stop here and wait for the user to test, stage, and commit the change.
+</plan_template>