Initial commit

references/audit-report-template.md

@@ -0,0 +1,296 @@
+# Skill Review Audit Report Template
+
+Use this template to document skill audit findings.
+
+---
+
+## Skill Review Report: [SKILL-NAME]
+
+**Date**: YYYY-MM-DD
+**Audit Type**: Deep review / Quick check
+**Trigger**: [Why review was performed]
+**Time Spent**: [Duration]
+**Auditor**: Claude (Sonnet 4.5) / Human
+
+---
+
+### Executive Summary
+
+**Status**: ✅ PASS / ⚠️ WARN / ❌ FAIL
+
+**Findings**:
+- 🔴 Critical: [N] issues
+- 🟡 High: [N] issues
+- 🟠 Medium: [N] issues
+- 🟢 Low: [N] issues
+
+**Action Required**: [None / Minor fixes / Comprehensive refactor]
+
+**Version Bump**: [None / Patch / Minor / Major]
+
+---
+
+### Quick Validation Checks
+
+| Check | Rule | Status | Actual |
+|-------|------|--------|--------|
+| Name Length | Max 64 chars | ✅/❌ | [N chars] |
+| Name Format | `^[a-z0-9-]+$` | ✅/❌ | [pattern] |
+| Reserved Words | No "anthropic"/"claude" | ✅/❌ | [found/none] |
+| Description Length | Max 1024 chars | ✅/❌ | [N chars] |
+| Description XML Tags | No `<tag>` content | ✅/❌ | [found/none] |
+| SKILL.md Lines | <500 lines | ✅/❌ | [N lines] |
+| Third-Person Style | "This skill..." not "You should..." | ✅/❌ | [compliant/issues] |
+
+---
+
+### Progressive Disclosure Score
+
+**Architecture Compliance**: [Good / Needs Work / Major Issues]
+
+- **Reference Depth**: ✅/❌ One level deep from SKILL.md
+- **TOC for Long Files**: ✅/❌ Files >100 lines have table of contents
+- **3-Tier Model**:
+  - Level 1 (Metadata): ✅/❌ Concise, always-loaded
+  - Level 2 (SKILL.md): ✅/❌ <500 lines, core content
+  - Level 3 (Resources): ✅/❌ On-demand loading
+- **Nested References**: [N found] (should be 0)
+
+**Token Efficiency Notes**:
+- [Observations about context usage]
+- [Suggestions for optimization]
+
+---
+
+### Conciseness Rating
+
+**Score**: [1-10] (10 = maximally concise)
+
+**Over-Explained Concepts** (Claude already knows):
+- [Concept 1]: [Where found]
+- [Concept 2]: [Where found]
+
+**Verbose Sections**:
+- [Section]: Could reduce by [N] lines
+- [Section]: Duplicates information from [other section]
+
+**Degrees of Freedom Assessment**:
+- Task Fragility: [High / Medium / Low]
+- Current Freedom Level: [High / Medium / Low]
+- Appropriate: ✅/❌
+
+**Terminology Consistency**:
+- ✅/❌ Same concept uses same words throughout
+- Inconsistencies found: [List if any]
+
+---
+
+### Anti-Pattern Detection
+
+**Count**: [N] anti-patterns found
+
+- ❌/✅ Windows-style paths (`\` instead of `/`)
+- ❌/✅ Inconsistent terminology
+- ❌/✅ Time-sensitive information ("as of 2024")
+- ❌/✅ Too many options without defaults
+- ❌/✅ Deeply nested references (>1 level)
+- ❌/✅ Vague phrases without examples
+- ❌/✅ Missing input/output examples
+- ❌/✅ No feedback loops in workflows
+
+**Specific Findings**:
+1. [Anti-pattern]: [Location and fix]
+2. [Anti-pattern]: [Location and fix]
+
+---
+
+### Testing & Evaluation Review
+
+**Test Coverage**: [Excellent / Good / Needs Improvement / Missing]
+
+- **Test Scenarios**: [N] found (minimum 3 required)
+  1. [Scenario 1]
+  2. [Scenario 2]
+  3. [Scenario 3]
+
+- **Multi-Model Consideration**: ✅/❌
+  - Haiku: [Notes]
+  - Sonnet: [Notes]
+  - Opus: [Notes]
+
+- **Real Problem Validation**: ✅/❌
+  - Skill solves actual user pain points: [Evidence]
+  - Not theoretical/imagined problems: [Assessment]
+
+- **Production Testing Evidence**:
+  - ✅/❌ Evidence provided
+  - Details: [What was tested, results]
+
+---
+
+### Security & MCP Review
+
+- **External URL Fetches**: [N] found
+  - URLs: [List with risk assessment]
+  - Recommendation: [Keep / Remove / Add warning]
+
+- **MCP Tool References**:
+  - ✅/❌ All fully qualified (ServerName:tool_name)
+  - Issues: [List if any]
+
+- **Error Handling Quality**:
+  - ✅/❌ "Solve, don't punt" pattern followed
+  - Silent failures: [List if any]
+
+- **Script Security**:
+  - Permissions: [Assessment]
+  - Warnings: [Any missing warnings]
+
+---
+
+### Detailed Findings
+
+#### Issue #1: [Short Description]
+
+**Severity**: 🔴 CRITICAL / 🟡 HIGH / 🟠 MEDIUM / 🟢 LOW
+
+**Location**: `file.ts:123` or SKILL.md section
+
+**Problem**:
+[Clear description of what's wrong]
+
+**Evidence**:
+- Official docs: [URL]
+- GitHub issue: [URL] (if applicable)
+- npm: `npm view package version` output
+- Production example: [GitHub repo URL]
+
+**Impact**:
+[What happens if not fixed]
+
+**Fix**:
+```diff
+- old code
++ new code
+```
+
+**Breaking Change**: Yes / No
+
+---
+
+[Repeat for each issue]
+
+---
+
+### Remediation Summary
+
+**Files Deleted** ([N]):
+- `path/to/file.ts` (reason)
+
+**Files Created** ([N]):
+- `path/to/file.ts` (purpose)
+
+**Files Modified** ([N]):
+- `path/to/file.ts` (changes)
+
+**Lines Changed**:
+- Removed: [N] lines
+- Added: [N] lines
+- Net: [±N] lines
+
+---
+
+### Version Update
+
+**Version**: [old] → [new]
+
+**Reason**: [Breaking changes / New features / Bug fixes]
+
+**Migration Path**: [If breaking changes, how to upgrade]
+
+**Changelog**:
+```markdown
+v[new] (YYYY-MM-DD)
+[BREAKING if applicable]: [Summary]
+
+Critical:
+- [List critical fixes]
+
+High:
+- [List high-priority fixes]
+
+Medium:
+- [List medium fixes]
+
+Low:
+- [List low fixes]
+
+Migration: [How to upgrade if breaking]
+```
+
+---
+
+### Post-Fix Verification
+
+**Discovery Test**:
+- ✅ / ❌ Skill recognized by Claude
+- ✅ / ❌ Metadata loads correctly
+
+**Template Test** (if applicable):
+- ✅ / ❌ Templates build successfully
+- ✅ / ❌ No TypeScript errors
+- ✅ / ❌ Dependencies resolve
+
+**Consistency Check**:
+- ✅ / ❌ SKILL.md vs README.md match
+- ✅ / ❌ No contradictions in references/
+- ✅ / ❌ Bundled Resources list accurate
+
+**Code Quality**:
+- ✅ / ❌ No TODO markers
+- ✅ / ❌ No broken links
+- ✅ / ❌ All imports valid
+
+**Commit**:
+- Hash: [git hash]
+- Pushed: ✅ / ❌
+
+---
+
+### Lessons Learned
+
+1. [Key takeaway #1]
+2. [Key takeaway #2]
+3. [Key takeaway #3]
+
+---
+
+### Recommendations
+
+**Immediate**:
+- [Action items that must be done now]
+
+**Future**:
+- [Improvements for next review cycle]
+
+**Process**:
+- [Suggestions for improving review process]
+
+---
+
+### Appendix
+
+**Automation Output** (`./scripts/review-skill.sh`):
+```
+[Paste relevant script output]
+```
+
+**Manual Verification Notes**:
+- [Additional observations]
+- [Edge cases discovered]
+- [Questions for maintainer]
+
+---
+
+**Audit Complete**: YYYY-MM-DD
+**Result**: [Summary of final state]