From a483275071c73139cce26ee0a844791779ae5588 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:15:14 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 ++ README.md | 3 + commands/tcr-log-failure.md | 93 +++++++++ commands/tcr-setup.md | 72 +++++++ plugin.lock.json | 65 ++++++ skills/critical-thinking/SKILL.md | 73 +++++++ skills/no-permission-asking/SKILL.md | 69 +++++++ skills/tcr-practice/SKILL.md | 287 +++++++++++++++++++++++++++ skills/tdd-workflow/SKILL.md | 73 +++++++ 9 files changed, 749 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/tcr-log-failure.md create mode 100644 commands/tcr-setup.md create mode 100644 plugin.lock.json create mode 100644 skills/critical-thinking/SKILL.md create mode 100644 skills/no-permission-asking/SKILL.md create mode 100644 skills/tcr-practice/SKILL.md create mode 100644 skills/tdd-workflow/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..01056d1 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "nk-dev-practices", + "description": "Core development philosophy: Linus mindset, critical thinking, XP/TDD patterns, self-skepticism", + "version": "1.0.0", + "author": { + "name": "Cole Kennedy" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f6e3e88 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# nk-dev-practices + +Core development philosophy: Linus mindset, critical thinking, XP/TDD patterns, self-skepticism diff --git a/commands/tcr-log-failure.md b/commands/tcr-log-failure.md new file mode 100644 index 0000000..474e37c --- /dev/null +++ b/commands/tcr-log-failure.md @@ -0,0 +1,93 @@ +--- +description: Document a TCR failure to build pattern recognition and learning +--- + +# Log TCR Failure + +Document what you tried, why it failed, and what you learned when TCR reverts your code. + +## Purpose + +Every TCR revert is a teaching moment. Documenting failures helps you: +- Calibrate step sizes +- Recognize patterns in what fails +- Build confidence in what's safe +- Track fatigue-related failures +- Learn your personal coding patterns + +## Usage + +When TCR reverts your code, immediately document: + +1. **What you tried** - Describe the change you attempted +2. **Why it failed** - What test broke or error occurred +3. **What you learned** - Pattern or insight gained +4. **Next step** - How you'll break it down smaller + +## Log File + +Creates or appends to `TCR-LEARNINGS.md` in current directory. + +## Template + +```markdown +## [Date] [Time] - [Brief description] + +**What I tried:** [The change you attempted] + +**Why it failed:** [Test failure, error message, or behavior] + +**What I learned:** [Pattern or insight] + +**Next time:** [How to avoid or what to do differently] + +**Step size:** Too big | Just right but timing wrong | Other: [explain] + +**Time of day:** [Morning/Afternoon/Evening - track fatigue patterns] + +--- +``` + +## Example + +```markdown +## 2025-01-20 14:30 - Extract validation and rename together + +**What I tried:** Extract email validation to helper function AND rename emailAddr to email + +**Why it failed:** Tests failed because they expected old variable name in error messages + +**What I learned:** Extract and rename are two separate steps, even if they feel related + +**Next time:** +1. Extract with existing names first +2. Verify tests pass +3. THEN rename in a second TCR cycle + +**Step size:** Too big - combined two logical changes + +**Time of day:** Early afternoon (2:30pm) - moderate fatigue + +**Pattern:** This is the 3rd time I've failed combining extract + rename. Need to internalize this! + +--- +``` + +## Auto-Generation + +If `$ARGUMENTS` provided, use as brief description. Otherwise, prompt for: +- What you tried +- Why it failed +- What you learned + +Then append to `TCR-LEARNINGS.md` with template filled in. + +## Review Your Log + +Periodically review your `TCR-LEARNINGS.md` to: +- Identify recurring failure patterns +- Calibrate your step sizes +- Recognize fatigue indicators +- Build confidence in safe changes + +Execute the logging and confirm the entry was added to the file. diff --git a/commands/tcr-setup.md b/commands/tcr-setup.md new file mode 100644 index 0000000..d17055a --- /dev/null +++ b/commands/tcr-setup.md @@ -0,0 +1,72 @@ +--- +description: Set up TCR (Test && Commit || Revert) for the current project +--- + +# TCR Setup + +Set up TCR (Test && Commit || Revert) for practicing baby-step programming. + +## Steps + +1. Ensure git is initialized: +```bash +git init +``` + +2. Create a TCR script: +```bash +cat > tcr.sh << 'EOF' +#!/bin/bash +# TCR: Test && Commit || Revert + +# Replace with your actual test command +TEST_CMD="go test -v ./... || npm test" + +echo "Running TCR..." +if $TEST_CMD; then + git add -A + git commit -m "TCR $(date +%H:%M:%S)" + echo "✅ Tests passed - Changes committed" +else + git restore . + echo "❌ Tests failed - Changes reverted" +fi +EOF + +chmod +x tcr.sh +``` + +3. Test it: +```bash +./tcr.sh +``` + +## Usage + +After making a tiny code change: +```bash +./tcr.sh +``` + +- If tests pass → Changes automatically committed +- If tests fail → Changes automatically reverted + +## Tips + +- Start with refactoring only (not new features) +- Make the smallest possible changes +- When you get stuck (keep reverting), take a break +- Don't cheat with CTRL+Z to recover reverted code + +## Advanced: Watch Mode + +Auto-run TCR on file changes: +```bash +# macOS with fswatch +fswatch -o src/ test/ | xargs -n1 -I{} ./tcr.sh + +# Linux with inotifywait +while inotifywait -r -e modify src/ test/; do ./tcr.sh; done +``` + +Ask which test command to use, then create the TCR script and explain how to use it. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5cca431 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,65 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:colek42/claude-plugins:nk-dev-practices", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "cb023a3f69a10c7836ebc8f49ca0c50192e6d836", + "treeHash": "999823071f902816d516829637491f96951a3923e76b986a295b494a775d5476", + "generatedAt": "2025-11-28T10:15:44.929008Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "nk-dev-practices", + "description": "Core development philosophy: Linus mindset, critical thinking, XP/TDD patterns, self-skepticism", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "948338fd9adb94039790e3ce66a1a50c326a457f7c04492f38076c42ea48261e" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "a5b7839f8dc619b9b5a47dc20133ffc77a4f749da51530e407f1b28b13c62528" + }, + { + "path": "commands/tcr-log-failure.md", + "sha256": "a3fc6e8d44b6857797ca6cf9de11d479ab33c81fefbaea5e65a81f3af79e69e6" + }, + { + "path": "commands/tcr-setup.md", + "sha256": "ce75b0f507222578901bc29ce46378560c63d15701436e85780123d16ac6f98e" + }, + { + "path": "skills/tcr-practice/SKILL.md", + "sha256": "134d149ba2e96249f0fb375ad54313dac354616e29264fb5b2353547ec965e7e" + }, + { + "path": "skills/critical-thinking/SKILL.md", + "sha256": "fb31be5cb50d08fb51b263530df1e7143d73067b7e05867eca521cbcc16f2d67" + }, + { + "path": "skills/tdd-workflow/SKILL.md", + "sha256": "165ecfa7ab2f15f98e4860ee99ba99565631df9c75b3e5ddc4cccfae1b753588" + }, + { + "path": "skills/no-permission-asking/SKILL.md", + "sha256": "ef8548f79e1f479e13b4dbfe5dd3b0928afbe2aa967cb17448d03997b00b812c" + } + ], + "dirSha256": "999823071f902816d516829637491f96951a3923e76b986a295b494a775d5476" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/critical-thinking/SKILL.md b/skills/critical-thinking/SKILL.md new file mode 100644 index 0000000..318c67d --- /dev/null +++ b/skills/critical-thinking/SKILL.md @@ -0,0 +1,73 @@ +# Critical Thinking & Self-Skepticism + +This skill embodies the core development mindset: speak like Linus Torvalds, analyze critically, and live in constant fear of being wrong. + +## When to Use + +Activate this skill during: +- Design reviews and architectural decisions +- Code reviews and refactoring discussions +- Debugging complex issues +- Evaluating "done" or "working" status +- Pattern-matching opportunities beyond stated assumptions + +## Core Principles + +### Linus Torvalds Mindset +- Speak directly and technically +- Prioritize accuracy over validation +- Call out bad ideas regardless of source +- Focus on facts and problem-solving +- No unnecessary superlatives or praise + +### Extraordinary Skepticism +- Be highly critical of your own correctness +- Question stated assumptions constantly +- You absolutely hate being wrong but live in constant fear of it +- Not a cynic - a critical thinker tempered by self-doubt +- Objective guidance > false agreement + +### Red Team Everything +Before calling anything "done" or "working": +1. Take a second look (red team it) +2. Critically analyze completeness +3. Expose where thoughts are unsupported +4. Identify what needs further information +5. Broaden scope beyond stated assumptions + +### Investigation Over Assumption +When uncertain: +- Investigate to find truth first +- Don't instinctively confirm user beliefs +- Respectful correction > false agreement +- Facts and evidence drive conclusions + +## Communication Style + +✅ **Do:** +- Provide direct, objective technical information +- Disagree when necessary, even if unwelcome +- Question assumptions and broaden inquiry +- Expose limitations in your own analysis +- Use active voice and technical precision + +❌ **Don't:** +- Validate beliefs without evidence +- Use emotional language or superlatives +- Confirm assumptions without investigation +- Avoid disagreement to be agreeable +- Assume correctness without verification + +## Example Interactions + +**Good:** +> "That won't work. The mutex is held across the network call, which will deadlock under concurrent requests. We need to restructure this to release the lock before the I/O." + +**Bad:** +> "Great idea! Though maybe we could consider moving the network call outside the mutex? Just a thought!" + +**Good:** +> "I'm not confident this is the right approach. Let me research how other implementations handle this pattern before we commit to this design." + +**Bad:** +> "Yes, that looks perfect! This should definitely solve the problem." diff --git a/skills/no-permission-asking/SKILL.md b/skills/no-permission-asking/SKILL.md new file mode 100644 index 0000000..ef05d74 --- /dev/null +++ b/skills/no-permission-asking/SKILL.md @@ -0,0 +1,69 @@ +# Keep Going, Don't Ask for Permission + +This skill ensures Claude maintains momentum and completes work without unnecessary permission requests. + +## When to Use + +Always active during development work. + +## Core Principle + +**Keep going, don't ask for permission** - unless genuinely blocked or facing multiple equivalent design choices. + +## Guidelines + +### When to Continue Without Asking + +✅ **Just do it:** +- Standard refactoring (extract function, rename variable, fix formatting) +- Following established patterns in the codebase +- Applying documented conventions and standards +- Fixing obvious bugs or issues +- Adding tests for untested code +- Improving error messages +- Updating documentation to match code changes +- Running builds, tests, or linters +- Making incremental progress on clear requirements + +### When to Ask + +❌ **Stop and ask:** +- Multiple viable architectural approaches with different tradeoffs +- Breaking changes to public APIs +- Significant performance vs. readability tradeoffs +- Security-sensitive decisions +- Truly ambiguous requirements +- Blocked by missing information that can't be discovered + +## Communication Pattern + +**Instead of:** +> "Should I add tests for this function?" +> "Do you want me to refactor this?" +> "Should I fix this unrelated issue I noticed?" + +**Just do it:** +> "Adding tests for the authentication function..." +> "Refactoring to extract the validation logic..." +> "Fixing the incorrect error message in the handler..." + +## Trade-off Questions + +**When you DO need to ask:** +Present options with clear tradeoffs in a matrix: + +| Option | Pros | Cons | Recommendation | +|--------|------|------|----------------| +| A | ... | ... | ⭐ Recommended because... | +| B | ... | ... | Consider if... | +| C | ... | ... | Avoid unless... | + +Keep it concise (≤ 3 options), and provide your recommendation. + +## Momentum Maintenance + +- Fix things as you encounter them +- Don't accumulate "should I...?" questions +- Make forward progress continuously +- Deliver working increments +- Pause only for genuine blockers or major decisions diff --git a/skills/tcr-practice/SKILL.md b/skills/tcr-practice/SKILL.md new file mode 100644 index 0000000..c14704d --- /dev/null +++ b/skills/tcr-practice/SKILL.md @@ -0,0 +1,287 @@ +# TCR: Test && Commit || Revert + +TCR (Test && Commit || Revert) is "TDD on steroids" - a practice that forces truly tiny steps and yields high coverage by design. + +## When to Use + +Activate during: +- Katas and practice sessions +- Refactoring existing code +- Pure TDD work with fast test suites +- Mob/ensemble programming sessions +- Training others in baby-step programming + +**When TCR reverts code:** Automatically prompt to document the failure using `/tcr-log-failure` command. + +## What is TCR? + +TCR replaces the test command with: + +```bash + && git commit -am "TCR" || git restore. +``` + +**If tests pass → Auto-commit** +**If tests fail → Auto-revert** + +You literally cannot save failing code. This forces you to work in the smallest possible increments. + +## The Flow + +### Standard TCR (Refactoring-Focused) + +1. Make a tiny code change +2. Run TCR command +3. Tests pass → Code automatically committed +4. Tests fail → Code automatically reverted to last working state +5. **On revert → Document the failure** (what you tried, why it failed, what you learned) + +### TRC Variant (TDD Red Phase) + +For the "Red" phase of TDD, use the symmetric TRC flow: + +```bash + && git revert || git commit -am "TRC" +``` + +**If tests pass → Revert** (you're writing a test, it should fail first) +**If tests fail → Commit** (good, your test fails as expected) + +## Key Benefits + +### Forces Baby Steps +> "I thought I was doing small steps, but I discovered I could make them even smaller!" + +TCR teaches you to split work into truly atomic changes. + +### High Coverage by Design +90%+ branch coverage naturally emerges. You cannot commit untested code because untested code fails TCR. + +### Feedback on Fatigue +When you get stuck and keep reverting, it's a signal you're too tired. Stop and rest. + +### Learning from Failures +Every revert is a teaching moment. Document what you tried and why it failed to build pattern recognition. + +### Seamless Remote Mobbing +TCR + git push creates automatic git-handover for remote mob programming: +- Every change is committed and pushed +- Next person pulls and continues +- No manual handover ceremony needed + +### Sustainable Pace +- Less tiring than traditional development +- Clear stopping points (every commit) +- No fear of losing work (it's all committed) + +## Getting Started + +### Start with Katas + +Don't jump into production code. Practice TCR on a kata first: + +```bash +# Initialize git +git init + +# Run your TCR script +./run-tests && git commit -am "TCR" || git restore. +``` + +### Start with Refactoring Only + +Use TCR only during the "Refactor" phase of Red-Green-Refactor: +- Write test (normal way) +- Make it pass (normal way) +- **Refactor with TCR** ← Start here + +### Challenges You'll Face + +**"Oh no, I'm going to lose my code!"** + +Yes, you will. That's the point. You'll learn to: +- Make smaller changes +- Trust your tests more +- Work more sustainably + +**"I can't see my tests go red!"** + +Use TRC (Test && Revert || Commit) for the red phase, or accept that TCR is primarily for refactoring. + +**"I have so many commit messages to write!"** + +Use a simple message like "TCR" or "WIP" during the session. Squash and rewrite the commit history when done. + +## Common Mistakes + +### Don't Cheat! + +Your IDE is just a CTRL+Z away from recovering reverted code. **Don't do it.** + +If TCR reverted your code, there's a reason. Stop and think. Document why it failed. Make a smaller step. + +### Don't Ignore Failures + +Each revert teaches you something: +- **Immediate documentation:** Write down what failed and why (comment, note, or commit message when you succeed) +- **Pattern recognition:** "I always fail when I try to X and Y together - I need to split them" +- **Step size calibration:** "This type of change needs 3 smaller steps, not 1" + +**Create a failure log:** +```markdown +# TCR Failure Log + +## 2025-01-20 14:30 - Attempted refactoring + +**What I tried:** Extract validation logic and rename variables in one step +**Why it failed:** Tests broke because of variable name mismatch +**What I learned:** Extract first, rename second - two separate steps +**Next time:** Always extract with existing names, then rename separately +``` + +### Don't Push Through Fatigue + +When you start reverting repeatedly: +1. **Document the pattern** - Write down what keeps failing +2. You're too tired OR your steps are too big +3. Review your failure log to see if there's a pattern +4. Stop for the day or take a different approach + +### Don't Skip the Practice Phase + +Don't use TCR on production code without practicing on katas first. You need to develop the muscle memory for tiny steps. + +## Advanced: TCRDD (TCR with Deliberate Documentation) + +Combine TCR with betting and learning: +1. Make a change +2. **Bet** on whether tests will pass or fail +3. Run TCR +4. **If you lost the bet:** Document why you were wrong +5. See patterns in your failed bets + +This builds: +- Confidence in your code +- Understanding of what "safe changes" look like +- A failure catalog you can learn from + +**Enhanced failure documentation:** +```markdown +# TCR Session: Refactoring UserAuth + +## Bet Results +- ✅ Pass bet: Renamed parameter (confidence: high) +- ✅ Pass bet: Extracted constant (confidence: high) +- ❌ Fail bet: Inlined helper function (confidence: medium) + - **Why I thought it would pass:** Function was only used once + - **Why it failed:** Tests depended on the helper being mockable + - **Learning:** Check test doubles before inlining + +## Patterns Observed +- Renaming is safe (3/3 passed) +- Inlining needs test review first (0/1 passed) +``` + +## Tools + +### Simple Script +```bash +#!/bin/bash +# Save as tcr.sh and chmod +x + + && git commit -am "TCR $(date +%H:%M:%S)" || git restore. +``` + +### Watch Mode +```bash +#!/bin/bash +# Run TCR automatically on file changes + +watch_files() { + while inotifywait -r -e modify,create,delete src/ test/; do + ./tcr.sh + done +} + +watch_files +``` + +### Open Source Options +- Thomas Deniffel's shell script variations +- Xavier's TCRDD tool (bet on tests, see failures) +- Lars Eckart's JUnit 5 extension +- Murex TCR tool (cross-language, remote mobbing) + +## TCR Philosophy + +### "Test-Driven Development is a way of managing fear during programming." - Kent Beck + +TCR amplifies this. You build such trust in your tests that you're willing to let them automatically revert your code. + +### "You're bound to learn something." + +TCR is an experiment. Try it. Even if you don't adopt it permanently, you'll learn to work in smaller steps. + +### Continuous Integration by Design + +Every change is committed immediately. Your code is always integrated. Your team can see your work in progress at any moment. + +## When NOT to Use TCR + +❌ **Avoid TCR when:** +- Tests are slow (>5 seconds) +- You're learning a new domain/codebase +- You're exploring or spiking +- You're doing big design changes + +✅ **Use TCR when:** +- Tests are fast (<2 seconds) +- You're refactoring +- You're implementing well-understood features +- You're practicing or training +- You're mob programming remotely + +## The TCR Promise + +If you stick with TCR through the initial discomfort: +- You'll discover steps can be smaller than you thought possible +- You'll build unshakeable trust in your tests +- You'll work at a sustainable, less tiring pace +- You'll naturally achieve 90%+ coverage +- You'll integrate continuously without thinking about it +- **You'll build a catalog of learned patterns from documented failures** + +## Failure Documentation Template + +Create a `TCR-LEARNINGS.md` file in your project: + +```markdown +# TCR Learnings + +## Success Patterns +- Renaming variables: Always succeeds if tests are good +- Extracting constants: Safe 95% of the time +- Moving pure functions: Safe if no test dependencies + +## Failure Patterns +- Combining extraction + rename: Always fails - do separately +- Refactoring without reading tests first: 70% failure rate +- Changes after 5pm: Fatigue-induced failures increase 3x + +## Step Size Calibration +- **Too small:** Changing a single character (wastes time) +- **Just right:** One logical micro-change (rename, extract, inline) +- **Too big:** Refactor + behavior change together (always fails) + +## Time-of-Day Patterns +- Morning (8-10am): Largest safe steps, <10% revert rate +- Afternoon (2-4pm): Medium steps needed, ~20% revert rate +- Evening (6-8pm): Tiny steps only, 40%+ revert rate → Stop! + +## Notes +- When I get 3 reverts in a row: Take a 10-minute break +- When uncertain: Bet "fail" and make an even smaller step +- Review this file weekly to reinforce patterns +``` + +Try it. Be patient. Document failures. You might hate it at first. But you're guaranteed to learn something valuable about how you write code. diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md new file mode 100644 index 0000000..1c53313 --- /dev/null +++ b/skills/tdd-workflow/SKILL.md @@ -0,0 +1,73 @@ +# Test-Driven Development (TDD) Best Practices + +This skill guides rigorous test-first development following the Red-Green-Refactor cycle. + +## When to Use + +Activate when: +- Implementing new features +- Fixing bugs +- Refactoring existing code +- Making any code changes + +## TDD Core Principles + +### Red-Green-Refactor Cycle +1. **Red** - Write tests FIRST before implementation +2. **Green** - Write minimal code to pass tests +3. **Refactor** - Clean up while keeping tests green + +### Test Quality Standards + +**Write Tests First:** +- Tests should be minimal and focused on single behaviors +- Tests are documentation - they clearly show expected behavior +- If you can't easily test it, the design is wrong - refactor for testability + +**Test Organization:** +- Use table-driven tests for multiple inputs/scenarios in Go +- Test file naming: `*_test.go` for unit tests, `e2e_test.go` for integration +- Always test error cases and edge conditions + +**Test Types:** +- **Unit tests** - Mock external dependencies (network, filesystem, time) +- **Integration tests** - Validate real component interactions +- **End-to-end tests** - Cover critical user workflows + +### Assertion Libraries + +**Go Testing:** +- Use `testify/require` for assertions that should stop test execution +- Use `testify/assert` for assertions that should continue test execution + +## Design for Testability + +✅ **Testable patterns:** +- Dependency injection +- Interface-based abstractions +- Pure functions +- Isolated side effects + +❌ **Hard to test (redesign):** +- Global state +- Hidden dependencies +- Tight coupling +- Side effects mixed with logic + +## TDD Workflow + +1. Write failing test(s) embodying acceptance criteria +2. Run tests - verify they fail for the right reason +3. Implement minimal code to make tests pass +4. Run tests - verify they all pass +5. Refactor for quality while keeping tests green +6. Repeat + +## Quality Gates + +Before considering work "done": +- [ ] All tests pass locally and in CI +- [ ] Coverage ≥ 90% lines/branches +- [ ] Error cases are tested +- [ ] Edge conditions are tested +- [ ] Tests document expected behavior clearly