Core workflows: TDD, verification, brainstorming - essential capabilities always loaded

version
1.0.0

Install

/plugin install core@dot-claude

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude-old.

Contents

Discovered from source

Skills 4

Brainstorming Ideas Into Designs

Overview

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.

Announce at start: "I'm using the brainstorming skill to refine this idea into a design."

Progress Tracking

Create TodoWrite todos for each phase:

  • Understanding: Clarify the problem space
  • Exploring: Investigate alternative approaches
  • Presenting: Document proposed design
  • Handoff: Transition to implementation

Mark each phase as in_progress when starting, completed when done. This makes progress visible and prevents skipping phases.

Using AskUserQuestion

Use the AskUserQuestion tool for structured decision points:

  • Scope and constraint gathering
  • Approach selection (after presenting options)
  • Design section validation
  • Documentation and implementation handoff

Keep free-form conversation for:

  • Context-specific clarifications
  • Deep-dive questions unique to this idea
  • Exploring edge cases and nuances

Principle: Structured questions for decisions, conversational for discovery.

The Process

Phase 1: Understanding the Idea

Step 1: Check project context

  • Read relevant files, docs, recent commits
  • Understand what exists before proposing what to build

Step 2: Gather initial constraints

Use AskUserQuestion to understand scope:

Question: "What is the scope of this feature?"
Header: "Scope"
Options:
- MVP / Proof of concept: Minimal viable implementation to validate the idea
- Production-ready: Full implementation with error handling, tests, and docs
- Enhancement: Adding to existing feature rather than building new

Step 3: Identify target users (if unclear)

Use AskUserQuestion when user type matters:

Question: "Who is the primary user of this feature?"
Header: "User"
Options:
- End users: External users of the application
- Developers: Engineers working with the codebase
- Both: Needs to serve multiple user types

Step 4: Gather constraints

Use AskUserQuestion with multiSelect for constraints:

Question: "What constraints should I consider?"
Header: "Constraints"
multiSelect: true
Options:
- Performance-critical: Speed and efficiency are primary concerns
- Backwards compatible: Must not break existing functionality
- Security-sensitive: Requires security review and hardening
- External dependencies: Integrates with third-party services

Step 5: Context-specific questions

Continue with free-form questions one at a time:

  • Purpose: What problem does this solve?
  • Success criteria: How will we know it works?
  • Any unique constraints or requirements

Phase 2: Exploring Approaches

Step 1: Identify 2-3 approaches

After understanding the idea, propose 2-3 different approaches:

  • Describe each briefly with trade-offs
  • Lead with your recommendation and explain why
  • Keep descriptions concise (2-3 sentences each)

Step 2: Get approach selection

Use the AskUserQuestion tool (do NOT output as plain text):

Question: "Which approach would you prefer?" Header: "Approach" Options:

  • [Approach A name] (recommended): [Brief description of why this is recommended]
  • [Approach B name]: [Brief description and trade-off]
  • [Approach C name]: [Brief description and trade-off] multiSelect: false

Generate option labels and descriptions dynamically based on the approaches identified.

Phase 3: Presenting the Design

Step 1: Present design in sections

Once approach is selected, present the design:

  • Break into sections of 200-300 words
  • Cover: architecture, components, data flow, error handling, testing
  • One section at a time

Step 2: Validate each section

After each section, use AskUserQuestion:

Question: "Does this section of the design look right?"
Header: "Feedback"
Options:
- Looks good: This section is accurate, proceed to next
- Minor tweaks: Small changes needed, I will specify
- Needs rethinking: This approach has issues, let's discuss

If "Minor tweaks" or "Needs rethinking" selected, pause for their input.

Step 3: Handle feedback

  • Looks good: Proceed to next section
  • Minor tweaks: Wait for their specification, apply changes, re-validate section
  • Needs rethinking: Discuss issues, potentially return to Phase 2

Phase 4: After the Design

Step 1: Documentation decision

Use the AskUserQuestion tool (do NOT output as plain text):

Question: "How should I proceed with documentation?" Header: "Docs" Options:

  • Save and commit: Write design doc and commit to git
  • Save only: Write design doc without committing
  • Skip docs: Proceed without saving design document multiSelect: false

Step 2: Save design (if chosen)

  • Write to docs/plans/YYYY-MM-DD-<topic>-design.md
  • Use elements-of-style:writing-clearly-and-concisely skill if available
  • Commit if "Save and commit" was selected

Step 3: Implementation handoff

Use the AskUserQuestion tool (do NOT output as plain text):

Question: "Ready to proceed with implementation?" Header: "Next step" Options:

  • Set up worktree: Create isolated workspace and write implementation plan
  • Just the plan: Write implementation plan in current workspace
  • Stop here: I will handle implementation separately multiSelect: false

Step 4: Execute choice

  • Set up worktree: Use workflow:git-worktrees, then workflow:writing-plans
  • Just the plan: Use workflow:writing-plans directly
  • Stop here: Report completion, offer to continue later

Key Principles

  • Structured for decisions, conversational for discovery - AskUserQuestion for clear choices, free-form for exploration
  • One question at a time - Don't overwhelm with multiple questions
  • YAGNI ruthlessly - Remove unnecessary features from all designs
  • Explore alternatives - Always propose 2-3 approaches before settling
  • Incremental validation - Present design in sections, validate each
  • Be flexible - Go back and clarify when something doesn't make sense

When to Skip AskUserQuestion

Use free-form text instead when:

  • The question is highly context-specific
  • Options would be artificial or unclear
  • You need open-ended exploration
  • The user has already indicated a preference conversationally

The "Other" option in AskUserQuestion always allows custom input, but some questions are better asked conversationally.

Integration

REQUIRED SUB-SKILLS (when continuing to implementation):

  • workflow:git-worktrees - If "Set up worktree" selected
  • workflow:writing-plans - For creating implementation plan

Pairs with:

  • elements-of-style:writing-clearly-and-concisely - For design documentation

Test-Driven Development (TDD)

Python Project Support

When working in Python projects (pyproject.toml or setup.py present):

Load patterns first:

Use Skill tool: python:python-testing

Commands:

  • Use uv run pytest path/to/test.py (not npm test)
  • Use uv run pytest path/to/test.py::test_name -v for single test

Fixtures: Use conftest.py patterns from python:python-testing

Overview

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

When to Use

Always:

  • New features
  • Bug fixes
  • Refactoring
  • Behavior changes

Exceptions (ask your human partner):

  • Throwaway prototypes
  • Generated code
  • Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete

Implement fresh from tests. Period.

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED - Write Failing Test

Write one minimal test showing what should happen.

```typescript test('retries failed operations 3 times', async () => { let attempts = 0; const operation = () => { attempts++; if (attempts < 3) throw new Error('fail'); return 'success'; };

const result = await retryOperation(operation);

expect(result).toBe('success'); expect(attempts).toBe(3); });

Clear name, tests real behavior, one thing
</Good>

<Bad>
```typescript
test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

Vague name, tests mock not code

Requirements:

  • One behavior
  • Clear name
  • Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

  • Test fails (not errors)
  • Failure message is expected
  • Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest code to pass the test.

```typescript async function retryOperation(fn: () => Promise): Promise { for (let i = 0; i < 3; i++) { try { return await fn(); } catch (e) { if (i === 2) throw e; } } throw new Error('unreachable'); } ``` Just enough to pass ```typescript async function retryOperation( fn: () => Promise, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise { // YAGNI } ``` Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

  • Test passes
  • Other tests still pass
  • Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

REFACTOR - Clean Up

After green only:

  • Remove duplication
  • Improve names
  • Extract helpers

Keep tests green. Don't add behavior.

Repeat

Next failing test for next feature.

Good Tests

QualityGoodBad
MinimalOne thing. "and" in name? Split it.test('validates email and domain and whitespace')
ClearName describes behaviortest('test1')
Shows intentDemonstrates desired APIObscures what code should do

Why Order Matters

"I'll write tests after to verify it works"

Tests written after code pass immediately. Passing immediately proves nothing:

  • Might test wrong thing
  • Might test implementation, not behavior
  • Might miss edge cases you forgot
  • You never saw it catch the bug

Test-first forces you to see the test fail, proving it actually tests something.

"I already manually tested all the edge cases"

Manual testing is ad-hoc. You think you tested everything but:

  • No record of what you tested
  • Can't re-run when code changes
  • Easy to forget cases under pressure
  • "It worked when I tried it" ≠ comprehensive

Automated tests are systematic. They run the same way every time.

"Deleting X hours of work is wasteful"

Sunk cost fallacy. The time is already gone. Your choice now:

  • Delete and rewrite with TDD (X more hours, high confidence)
  • Keep it and add tests after (30 min, low confidence, likely bugs)

The "waste" is keeping code you can't trust. Working code without real tests is technical debt.

"TDD is dogmatic, being pragmatic means adapting"

TDD IS pragmatic:

  • Finds bugs before commit (faster than debugging after)
  • Prevents regressions (tests catch breaks immediately)
  • Documents behavior (tests show how to use code)
  • Enables refactoring (change freely, tests catch breaks)

"Pragmatic" shortcuts = debugging in production = slower.

"Tests after achieve the same goals - it's spirit not ritual"

No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"

Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.

Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).

30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.

Common Rationalizations

ExcuseReality
"Too simple to test"Simple code breaks. Test takes 30 seconds.
"I'll test after"Tests passing immediately prove nothing.
"Tests after achieve same goals"Tests-after = "what does this do?" Tests-first = "what should this do?"
"Already manually tested"Ad-hoc ≠ systematic. No record, can't re-run.
"Deleting X hours is wasteful"Sunk cost fallacy. Keeping unverified code is technical debt.
"Keep as reference, write tests first"You'll adapt it. That's testing after. Delete means delete.
"Need to explore first"Fine. Throw away exploration, start with TDD.
"Test hard = design unclear"Listen to test. Hard to test = hard to use.
"TDD will slow me down"TDD faster than debugging. Pragmatic = test-first.
"Manual test faster"Manual doesn't prove edge cases. You'll re-test every change.
"Existing code has no tests"You're improving it. Add tests for existing code.

Red Flags - STOP and Start Over

  • Code before test
  • Test after implementation
  • Test passes immediately
  • Can't explain why test failed
  • Tests added "later"
  • Rationalizing "just this once"
  • "I already manually tested it"
  • "Tests after achieve the same purpose"
  • "It's about spirit not ritual"
  • "Keep as reference" or "adapt existing code"
  • "Already spent X hours, deleting is wasteful"
  • "TDD is dogmatic, I'm being pragmatic"
  • "This is different because..."

All of these mean: Delete code. Start over with TDD.

Example: Bug Fix

Bug: Empty email accepted

RED

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Verify RED

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Verify GREEN

$ npm test
PASS

REFACTOR Extract validation for multiple fields if needed.

Example: Bug Fix (Python)

Bug: Empty email accepted

RED

def test_rejects_empty_email():
    result = submit_form({"email": ""})
    assert result["error"] == "Email required"

Verify RED

$ uv run pytest tests/test_form.py::test_rejects_empty_email -v
FAILED: AssertionError: assert None == 'Email required'

GREEN

def submit_form(data: dict) -> dict:
    if not data.get("email", "").strip():
        return {"error": "Email required"}
    # ...

Verify GREEN

$ uv run pytest tests/test_form.py::test_rejects_empty_email -v
PASSED

REFACTOR Extract validation for multiple fields if needed.

Verification Checklist

Before marking work complete:

  • Every new function/method has a test
  • Watched each test fail before implementing
  • Each test failed for expected reason (feature missing, not typo)
  • Wrote minimal code to pass each test
  • All tests pass
  • Output pristine (no errors, warnings)
  • Tests use real code (mocks only if unavoidable)
  • Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

When Stuck

ProblemSolution
Don't know how to testWrite wished-for API. Write assertion first. Ask your human partner.
Test too complicatedDesign too complicated. Simplify interface.
Must mock everythingCode too coupled. Use dependency injection.
Test setup hugeExtract helpers. Still complex? Simplify design.

Debugging Integration

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.

Never fix bugs without a test.

Final Rule

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without your human partner's permission.

If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

Getting Started with Skills

MANDATORY FIRST RESPONSE PROTOCOL

Before responding to ANY user message, you MUST complete this checklist:

  1. ☐ List available skills in your mind
  2. ☐ Ask yourself: "Does ANY skill match this request?"
  3. ☐ If yes → Use the Skill tool to read and run the skill file
  4. ☐ Announce which skill you're using
  5. ☐ Follow the skill exactly

Responding WITHOUT completing this checklist = automatic failure.

Critical Rules

  1. Follow mandatory workflows. Brainstorming before coding. Check for relevant skills before ANY task.

  2. Execute skills with the Skill tool

Common Rationalizations That Mean You're About To Fail

If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill.

  • "This is just a simple question" → WRONG. Questions are tasks. Check for skills.
  • "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills.
  • "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills.
  • "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it.
  • "I remember this skill" → WRONG. Skills evolve. Run the current version.
  • "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills.
  • "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it.
  • "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything.

Why: Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.

If a skill for your task exists, you must use it or you will fail at your task.

Skills with Checklists

If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.

Don't:

  • Work through checklist mentally
  • Skip creating todos "to save time"
  • Batch multiple items into one todo
  • Mark complete without doing them

Why: Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.

Announcing Skill Usage

Before using a skill, announce that you are using it. "I'm using [Skill Name] to [what you're doing]."

Examples:

  • "I'm using the brainstorming skill to refine your idea into a design."
  • "I'm using the tdd skill to implement this feature."

Why: Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.

About these skills

Many skills contain rigid rules (TDD, debugging, verification). Follow them exactly. Don't adapt away the discipline.

Some skills are flexible patterns (architecture, naming). Adapt core principles to your context.

The skill itself tells you which type it is.

Instructions ≠ Permission to Skip Workflows

Your human partner's specific instructions describe WHAT to do, not HOW.

"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.

Red flags: "Instruction was specific" • "Seems simple" • "Workflow is overkill"

Why: Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.

Summary

Starting any task:

  1. If relevant skill exists → Use the skill
  2. Announce you're using it
  3. Follow what it says

Skill has checklist? TodoWrite for every item.

Finding a relevant skill = mandatory to read and use it. Not optional.

Verification Before Completion

Overview

Claiming work is complete without verification is dishonesty, not efficiency.

Core principle: Evidence before claims, always.

Violating the letter of this rule is violating the spirit of this rule.

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

The Gate Function

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Common Failures

ClaimRequiresNot Sufficient
Tests passTest command output: 0 failuresPrevious run, "should pass"
Linter cleanLinter output: 0 errorsPartial check, extrapolation
Build succeedsBuild command: exit 0Linter passing, logs look good
Bug fixedTest original symptom: passesCode changed, assumed fixed
Regression test worksRed-green cycle verifiedTest passes once
Agent completedVCS diff shows changesAgent reports "success"
Requirements metLine-by-line checklistTests passing

Red Flags - STOP

  • Using "should", "probably", "seems to"
  • Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
  • About to commit/push/PR without verification
  • Trusting agent success reports
  • Relying on partial verification
  • Thinking "just this once"
  • Tired and wanting work over
  • ANY wording implying success without having run verification

Rationalization Prevention

ExcuseReality
"Should work now"RUN the verification
"I'm confident"Confidence ≠ evidence
"Just this once"No exceptions
"Linter passed"Linter ≠ compiler
"Agent said success"Verify independently
"I'm tired"Exhaustion ≠ excuse
"Partial check is enough"Partial proves nothing
"Different words so rule doesn't apply"Spirit over letter

Key Patterns

Tests:

✅ [Run test command] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Looks correct"

Regression tests (TDD Red-Green):

✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
❌ "I've written a regression test" (without red-green verification)

Build:

✅ [Run build] [See: exit 0] "Build passes"
❌ "Linter passed" (linter doesn't check compilation)

Requirements:

✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
❌ "Tests pass, phase complete"

Agent delegation:

✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
❌ Trust agent report

Why This Matters

From 24 failure memories:

  • your human partner said "I don't believe you" - trust broken
  • Undefined functions shipped - would crash
  • Missing requirements shipped - incomplete features
  • Time wasted on false completion → redirect → rework
  • Violates: "Honesty is a core value. If you lie, you'll be replaced."

When To Apply

ALWAYS before:

  • ANY variation of success/completion claims
  • ANY expression of satisfaction
  • ANY positive statement about work state
  • Committing, PR creation, task completion
  • Moving to next task
  • Delegating to agents

Rule applies to:

  • Exact phrases
  • Paraphrases and synonyms
  • Implications of success
  • ANY communication suggesting completion/correctness

The Bottom Line

No shortcuts for verification.

Run the command. Read the output. THEN claim the result.

This is non-negotiable.

Sponsors

Details

Marketplace
pproenca/dot-claude-old
Source
plugins/essential/core
Category
Community
License
MIT
Keywords
tdd, verification, brainstorming, core

More from pproenca/dot-claude-old

All 12