Tdd

flowchart TD
    START(["/tdd"]) --> INPUT{"What input?"}
    INPUT -->|GH Issue URL| ISSUE[Flow 1: Issue-First]
    INPUT -->|GH PR URL| PR[Flow 2: PR-First]
    INPUT -->|Local doc/task| LOCAL[Flow 3: Local-First]
    INPUT -->|Nothing| DETECT{Detect cluster}

    ISSUE --> ANALYZE[Read issue + conversation]
    ANALYZE --> CHECKPR{"Existing PR?"}
    CHECKPR -->|Own PR| PR
    CHECKPR -->|Other's PR| FORK{Fork or comment?}
    CHECKPR -->|No PR| RESEARCH["rca + plan + post to issue"]:::rca
    FORK --> RESEARCH
    RESEARCH --> WORKTREE["git:worktree"]:::git
    WORKTREE --> TDDCI

    PR --> RCACI["rca:ci"]:::rca
    RCACI --> TDDCI["tdd:ci"]:::tdd
    TDDCI -->|"3+ failures"| HS["tdd:hypershift"]:::tdd
    TDDCI -->|CI green| REVIEWS[Handle PR reviews]

    LOCAL --> KIND["tdd:kind"]:::tdd
    KIND -->|Tests pass| MOVETOPR[Create issue + PR]
    MOVETOPR --> PR

    DETECT -->|HyperShift| HS
    DETECT -->|Kind| KIND
    DETECT -->|None| TDDCI

    HS -->|CI green| REVIEWS
    REVIEWS -->|Changes needed| TDDCI
    REVIEWS -->|Approved| DONE([Merged])

    classDef tdd fill:#4CAF50,stroke:#333,color:white
    classDef rca fill:#FF5722,stroke:#333,color:white
    classDef git fill:#FF9800,stroke:#333,color:white

Follow this diagram as the workflow.

TDD Skills

Test-driven development workflows for iterative Kagenti development.

Entry Point Router

When /tdd is invoked, determine the entry point:

What was provided?
    │
    ├─ GitHub issue URL → Flow 1: Issue-First
    ├─ GitHub PR URL    → Flow 2: PR-First
    ├─ Local doc/task   → Flow 3: Local-First
    └─ Nothing          → Detect cluster, pick tdd:ci/kind/hypershift

Debug Mode (--debug)

Debug mode is only activated when /tdd is invoked as /tdd --debug <issue|PR|doc>.

When active, the workflow visually tracks progress through the diagram, highlighting the current node and showing edge traversal counts.

Setup

1. Create the debug output directory:

mkdir -p /tmp/kagenti/tdd/

2. Initialize the state file on first invocation. The script creates /tmp/kagenti/tdd/tdd-debug-state.json automatically.

At Each Phase Transition

Run the debug diagram script to update the visual:

python3 .claude/scripts/tdd-debug-diagram.py \
  --template .claude/skills/tdd/tdd-workflow.mmd \
  --current-node <NODE_ID> \
  --edge-counts '{"<FROM>-><TO>": <count>, ...}' \
  --output /tmp/kagenti/tdd/debug-diagram.mmd

Node IDs match the diagram: START, INPUT, ISSUE, PR, LOCAL, DETECT, ANALYZE, CHECKPR, FORK, RESEARCH, WORKTREE, RCACI, TDDCI, HS, KIND, MOVETOPR, REVIEWS, DONE.

State Tracking

The script maintains /tmp/kagenti/tdd/tdd-debug-state.json with:

• current_node - where in the workflow we are now
• edge_counts - how many times each edge has been traversed
• history - ordered list of nodes visited with timestamps

Propagation to Sub-Skills

When debug mode is active and the workflow enters a sub-skill (tdd:ci, tdd:kind, tdd:hypershift), pass the debug flag through:

1. Use the sub-skill's own .mmd template (e.g., .claude/skills/tdd:ci/tdd-ci-workflow.mmd)
2. Continue updating /tmp/kagenti/tdd/tdd-debug-state.json with the sub-skill's node transitions
3. When the sub-skill completes, resume tracking in the parent tdd-workflow.mmd

Report Current Position

After each script invocation, report to the user:

• Current node name and description
• Number of loop iterations (from edge counts)
• Path taken so far (from history)

Flow 1: /tdd <GH issue URL>

Step 1: Analyze the issue

Read the issue body and full conversation thread to understand:

• What's reported, what's expected, reproduction steps
• Latest state of discussion (comments may have new info)

Step 2: Check for existing work

gh pr list --repo kagenti/kagenti --state open --search "<issue-number>"

gh pr list --repo kagenti/kagenti --state closed --search "<issue-number>" --limit 5

Step 3: Route based on findings

Existing PR found?
    │
    ├─ YES, owned by current gh user
    │   → Jump to Flow 2 (/tdd <that PR URL>)
    │
    ├─ YES, owned by someone else
    │   → Offer options:
    │     a) Start new PR taking their branch as base
    │        (cherry-pick approach — our commits can be
    │        picked by the original author)
    │     b) Comment on their PR with analysis/fix suggestions
    │        (include git commands for them to cherry-pick)
    │   → If option a: create worktree from their branch
    │
    └─ NO existing PR
        → Continue to Step 4

Step 4: Research & Plan

Before writing ANY code:

1. RCA/Research — search codebase, trace root cause, check if tests cover this
2. Plan — what files change, what tests needed, approach options
3. Create mermaid diagrams to explain concepts (renders in GH comments)
4. Post to the issue (requires approval):
   • Findings and root cause
   • Questions where approach is unclear
   • Options with tradeoffs when multiple approaches exist
   • Mermaid diagrams to visualize the change
5. Wait for response if questions were posted

Step 5: Create worktree and implement

git worktree add .worktrees/<name> -b fix/<slug>-<number> upstream/main

Then enter the TDD loop (see "TDD Code Loop" below).

Flow 2: /tdd <GH PR URL>

Step 1: Assess PR state

gh pr view <number> --json author,state,reviewDecision,statusCheckRollup,mergeable,body,comments

Check ownership:

gh api user --jq '.login'

Step 2: Route based on ownership

PR owned by current gh user?
    │
    ├─ YES → Step 3 (work directly on the PR)
    │
    └─ NO → Offer options:
            a) Fork their branch into new PR, comment original
               with cherry-pick instructions for the fix
            b) Just comment with analysis/suggestions
            → If option a: create worktree from their branch

Step 3: Fix CI failures

Run rca:ci on failures, then tdd:ci fix loop. Escalate to tdd:hypershift after 3+ CI failures.

Step 4: Handle reviews (after CI green)

1. Fetch all review comments:

gh api repos/kagenti/kagenti/pulls/<number>/comments

gh pr view <number> --json reviews

2. Assess ALL comments before implementing:

   • Copilot/bot comments → auto-fix as commits
   • Human review (clear feedback) → one commit per logical item
   • Unclear feedback → post clarification question on PR
   • Multiple options → comment with options and tradeoffs

3. Self-review — review your own changes and post review output as PR comment

4. Back to Step 3 — wait for CI, check for new comments, repeat until approved

Flow 3: /tdd <local doc/task>

Step 1: Plan locally

Read the doc/task, plan the implementation.

Step 2: Create worktree and implement

git worktree add .worktrees/<name> -b feat/<slug> upstream/main

Step 3: Local TDD loop

Use tdd:kind for fast local iteration until Kind tests pass.

Step 4: Move to CI (when local tests pass)

Offer options:

1. Review the doc — ensure no local-only paths/links
2. Create GH issue from the doc (requires approval)
3. Create PR referencing the issue
4. Switch to Flow 2 (/tdd )

Branch Verification Gate

MANDATORY before the first commit in any TDD flow. Prevents pushing work to the wrong branch/PR.

Steps

1. Check current branch:

git branch --show-current

2. Check for open PRs on this branch:

gh pr list --head "$(git branch --show-current)" --json number,title,url --jq '.[] | "#\(.number) \(.title) \(.url)"'

3. Route based on findings:

Current branch has open PR?
    │
    ├─ YES → Ask user:
    │   "You are on branch <branch> which has open PR #<N>: <title>.
    │    Is this the right target for your current work?"
    │   │
    │   ├─ YES → Continue (commit to this branch)
    │   │
    │   └─ NO → Create worktree with new branch:
    │       git worktree add .worktrees/<name> -b <new-branch> upstream/main
    │       (switch all subsequent work to the worktree)
    │
    └─ NO open PR → Check if branch is main/upstream
        │
        ├─ On main → Create worktree with new branch (never commit to main)
        │
        └─ On feature branch without PR → Ask user:
            "You are on branch <branch> with no open PR.
             Continue here or create a new worktree?"

4. Record the verified branch in task metadata so subsequent commits skip re-verification.

Why This Exists

Without this gate, it's easy to accidentally push unrelated changes to an existing feature branch with an open PR, polluting that PR with unrelated commits.

Context-Safe Execution (MANDATORY for all TDD sub-skills)

Every command that produces more than ~5 lines of output MUST redirect to a file. This prevents context window pollution from build/test/kubectl output accumulating in context and being re-read on every subsequent turn.

# Session-scoped log directory — ALWAYS set before running commands
export LOG_DIR="${LOG_DIR:-${WORKSPACE_DIR:-/tmp}/kagenti-tdd}"
mkdir -p "$LOG_DIR"

Rules:

1. Redirect build/test/kubectl output: command > $LOG_DIR/name.log 2>&1; echo "EXIT:$?"
2. On success: report "OK" — if behavior seems wrong despite exit 0, use a subagent to analyze the log
3. On failure: use Task(subagent_type='Explore') to read the log file — NEVER in main context
4. The subagent reads the log and returns a concise summary (error cause, unexpected output, etc.)
5. Also use subagents to verify expected behavior — e.g., "check $LOG_DIR/test-run.log for trace export lines"

TDD Code Loop

All three flows eventually enter this loop:

0. Branch verification gate — verify branch/PR association (first commit only)
1. Write/fix code
2. test:write — write or update tests
3. test:review — verify test quality (no silent skips, assertive)
4. test:run-kind or test:run-hypershift — execute tests (output to $LOG_DIR)
5. Track progress — compare test results with previous run
6. cve:scan — scan for CVEs before pushing (BLOCKS if found)
7. git:commit — commit with proper format
8. git:rebase — rebase onto upstream/main
9. Push → ci:monitoring — wait for CI results
10. CI passes? → Handle reviews (Flow 2 Step 4). CI fails? → Back to step 1.

Commit Policy

Never revert. Never amend. Commits are permanent history.

Only commit when:

• All tests pass, OR
• At least 1 additional test passes compared to the previous commit (forward progress)

Commit 1: 8 pass, 5 fail  ← baseline, acceptable
Commit 2: 10 pass, 3 fail ← good, +2 passing
Commit 3: 11 pass, 2 fail ← good, +1 passing
(no commit): 9 pass, 4 fail ← DON'T COMMIT — regression, keep iterating

Rules

1. Don't commit until tests improve — at least 1 fewer failure than last commit
2. Never revert — keep the history, fix forward instead
3. Never amend — each commit is a checkpoint, session retrospective uses the history
4. Don't fix too many things at once — small focused commits are more stable
5. If stuck for too long — the session retrospective will catch it and improve the skill

Available Skills

Concurrency limit: Only one tdd:kind session at a time (one Kind cluster fits locally). Before routing to tdd:kind, run kind get clusters — if a cluster exists from another session, route to tdd:ci instead or ask the user.

Related Skills

• rca:ci - Root cause analysis from CI logs
• rca:hypershift - Root cause analysis with live cluster
• rca:kind - Root cause analysis on Kind
• ci:status - Check CI pipeline status
• test - Test writing, reviewing, and running
• test:review - Verify test quality before committing
• git:commit - Commit with proper format
• git:rebase - Rebase before pushing
• git:worktree - Create isolated worktrees
• repo:pr - PR creation conventions
• cve:scan - CVE scanning gate
• cve:brainstorm - CVE disclosure planning

Converted and distributed by TomeVault — claim your Tome and manage your conversions.