Initial commit: Claude Code foundations and improvements research

Conventions, community best practices research (Sept 2025 - March 2026),
and prioritized improvement backlog for Claude Code workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

improvements/skills-and-progressive-disclosure.md

@@ -0,0 +1,59 @@
+# Skills & Progressive Disclosure
+
+## Why This Matters
+
+Progressive disclosure is the single most powerful technique for managing context. Instead of putting everything in CLAUDE.md (which competes with Claude's ~50 built-in system instructions for attention), skills load domain knowledge **on demand** — only when relevant.
+
+Token savings: ~15,000 tokens per session recovered vs. loading everything upfront (82% improvement in one benchmark).
+
+## Current State
+
+- One custom skill: `reflect`
+- Skills symlinked from `~/dev/claude/custom-claude-skills/skills/` into `~/.claude/skills/`
+
+## Architecture
+
+```
+CLAUDE.md              # <200 lines, universal rules only
+.claude/skills/        # Domain knowledge loaded on demand
+.claude/rules/         # Path-scoped rules (YAML frontmatter for file pattern matching)
+```
+
+Skills use a three-stage loading: metadata (~100 tokens) -> full instructions (<5k tokens) -> bundled resources only as needed.
+
+## Suggested Skills to Build
+
+### /catchup
+Reads all changed files in your git branch when resuming work. Shows what changed since last session, reads relevant memory files, and summarises the current state.
+
+### /validate
+Codifies the "validate before deploying" principle. Runs helm template, kustomize build, linting, and type-checking as appropriate for the current project. Catches errors before they hit the cluster.
+
+### /deploy
+Standardised deploy workflow for cluster-bootstrap. Validates first, applies, then runs the appropriate verify script.
+
+### /security-audit
+Checks for secrets in code, insecure configurations, default credentials. Trail of Bits has 12+ open-source security skills that could be adapted.
+
+### /tdd
+Test-driven development workflow. Write tests first, then implement until tests pass. From `obra/superpowers` — 20+ production-proven skills.
+
+### /handoff
+Creates a structured handoff document (goals, progress, blockers, next steps) for session transitions. Useful before `/clear` or when hitting context limits.
+
+## Community Skills Worth Evaluating
+
+| Skill/Resource | Description |
+|---|---|
+| **obra/superpowers** | 20+ skills: TDD, systematic debugging, root cause tracing, brainstorming |
+| **Trail of Bits security skills** | 12+ security-focused skills for code auditing and vulnerability detection |
+| **cc-devops-skills** | IaC validation, shell script generation, DevOps workflows |
+| **Context Engineering Kit** | Advanced context engineering techniques with minimal token footprint |
+| **reddit-fetch** | Workaround for Claude's inability to fetch Reddit — uses Gemini CLI as fallback |
+
+## Best Practices
+
+- Limit to 20-30 high-quality skills. More than that degrades performance (Claude wastes tokens parsing descriptions).
+- Each skill should have one clear purpose and be self-contained.
+- Skills should be <200 lines / <5k tokens for the full instruction set.
+- Use YAML frontmatter in `.claude/rules/` for path-scoped conditional loading (e.g., rules that only apply to `*.yaml` files).