Initial commit

2025-11-29 18:15:14 +08:00
commit a483275071
9 changed files with 749 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ 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"
  ]
 }
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
 # nk-dev-practices
 Core development philosophy: Linus mindset, critical thinking, XP/TDD patterns, self-skepticism
--- a/commands/tcr-log-failure.md
+++ 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.
--- a/commands/tcr-setup.md
+++ 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.
--- a/plugin.lock.json
+++ 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": []
  }
 }
--- a/skills/critical-thinking/SKILL.md
+++ 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."
--- a/skills/no-permission-asking/SKILL.md
+++ 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
--- a/skills/tcr-practice/SKILL.md
+++ 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
 <test command> && 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
 <test command> && 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
 <your test command> && 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.
--- a/skills/tdd-workflow/SKILL.md
+++ 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
		`@@ -0,0 +1,3 @@`
							`# nk-dev-practices`

							`Core development philosophy: Linus mindset, critical thinking, XP/TDD patterns, self-skepticism`