# Plan Tdd > Turn a plain-language feature or module description into a reviewed TDD plan. Ask clarifying questions when context is missing, then design behavior cycles and assertions with edge, error, and security scenarios made explicit, and emit a self-contained HTML brief plus a machine-readable YAML plan that /tdd can implement. Use when the user says "plan a TDD", "design tests first", "spec-driven TDD", "what tests should this have", or wants a test plan reviewed before writing code. - Skill: `rlajous/plan-tdd` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add rlajous/plan-tdd` - Raw SKILL.md: https://api.skillmd.com/api/skills/rlajous/plan-tdd/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: rlajous (https://skillmd.com/u/rlajous) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rlajous/plan-tdd --- > Cross-runtime: follow [runtime compatibility](../../references/runtime-compatibility.md) for invocation, delegation, configuration precedence, state paths, and permissions. You are helping design a Test-Driven Development plan **before** any code is written. Take a plain-language description of what the user wants to build (optionally a ticket), fill missing context by asking the user, then produce a plan of **behavior cycles** (each a RED-GREEN-REFACTOR unit) and their **assertions**. Make edge cases, error paths, and high-risk scenarios (privilege escalation, data leakage, impersonation) explicit rather than leaving them off the radar. Deliver two artifacts: a self-contained HTML brief the user reviews, and a machine-readable YAML plan that `/tdd` can implement. This skill plans and reviews — it does **not** write implementation code, and it only scaffolds test skeletons after explicit approval (Step 11). Follow each step in order. ## Step 1: Load Configuration Check for configuration and context: ```bash if [ -f ".git-workflow/config.yaml" ]; then CONFIG_PATH=".git-workflow/config.yaml" elif [ -f ".claude/config.yaml" ]; then CONFIG_PATH=".claude/config.yaml" # legacy read-only fallback else CONFIG_PATH="" fi if [ -f ".git-workflow/pr-context.json" ]; then CONTEXT_PATH=".git-workflow/pr-context.json" elif [ -f ".claude/.pr-context.json" ]; then CONTEXT_PATH=".claude/.pr-context.json" # legacy read-only fallback else CONTEXT_PATH="" fi ``` **Load from the resolved `CONFIG_PATH` (if one exists):** ```yaml planTdd: outputDir: .git-workflow/plan-tdd maxQuestions: 6 testing: unit: auto lint: auto typeCheck: auto issueTracker: type: auto ``` **Default Values (when no config):** ```yaml planTdd: outputDir: .git-workflow/plan-tdd maxQuestions: 6 ``` ## Step 2: Parse Arguments Extract from `$ARGUMENTS`: ```text $ARGUMENTS ``` **Patterns to Extract:** | Pattern | Example | Meaning | | ------------ | ------------------------------------------- | -------------------- | | Ticket ID | `PROJ-123`, `ENG-456` | Issue tracker ticket | | GitHub Issue | `#789` | GitHub issue number | | Linear URL | `https://linear.app/.../ENG-456/...` | Extract ticket ID | | Jira URL | `https://....atlassian.net/browse/PROJ-123` | Extract ticket ID | | Remaining text | `Add role-based access to admin settings` | Feature description | **Parsing Logic:** - Extract ticket ID from URL if provided. Linear: `/issue/([A-Z]+-\d+)/`; Jira: `/browse/([A-Z]+-\d+)`; GitHub: `issues/(\d+)` or `#(\d+)`. - Everything not matched as a ticket/flag is the feature description. **Validation:** - Require at least a description **or** a ticket. If neither is present, ask the user what they want to build through the host's user-input mechanism before continuing. ## Step 3: Fetch Ticket Details (If ID Provided) Auto-detect the tracker by ticket format and available MCP servers, then fetch details. Skip this step entirely when the input is only a free-text description. - `^[A-Z]+-\d+$` with Linear MCP available -> Linear: `mcp__linear__get_issue(id: ticketId)` - `^[A-Z]+-\d+$` with Jira configured/available -> Jira: `mcp__jira__get_issue(issueKey: ticketId)` - `^#?\d+$` or GitHub URL -> GitHub Issues: `gh issue view {issue_number} --json title,body,labels` Extract title, description, acceptance criteria, and labels. Use labels to classify the plan `type`: | Label/Type | Plan type | | --------------------------------- | ---------- | | `bug`, `defect` | `bug_fix` | | `feature`, `Story`, `enhancement` | `feature` | | `refactor`, `tech-debt` | `refactor` | ## Step 4: Explore Codebase and Detect Test Framework Gather enough context to write a plan that fits the project. - Find files related to the description/ticket keywords, existing implementations in the same area, and neighboring test files. - Identify the test file naming convention, framework, test structure, and mock patterns from existing tests. - Detect the test framework and its run command. > Full per-language detection commands, tables, and the detection-results JSON shape: see `references/test-frameworks.md`. Record `test_framework`, `test_command`, and `test_file_pattern` for the plan. ## Step 5: Clarify Gaps This is the core of the skill: when context is missing, ask for it instead of guessing. From the description, ticket, and code, list the ambiguities and undefined behavior that would change the tests, focusing on: - **Scope and inputs** — what exactly is in and out of scope, valid input ranges, required vs optional fields. - **Edge and error behavior** — empty/absent data, limits, concurrency, invalid input, downstream failures, idempotency. - **Risk boundaries** — who is authorized for what (privilege scope), what data each actor may see (exposure), identity and impersonation rules, and tenant/isolation boundaries. Ask the user the highest-value questions through the host's user-input mechanism. Keep it bounded — no more than `planTdd.maxQuestions` (default 6). Record each answer as a resolved assumption; note anything left unanswered as an open question. Do not proceed to design until the risk boundaries are either answered or explicitly recorded as open. ## Step 6: Design the TDD Plan Enumerate **behavior cycles**. Each cycle is one RED-GREEN-REFACTOR unit describing an observable behavior, with concrete assertions that its RED test would make. For every cycle capture: - `id` (`BC-001`, `BC-002`, ...) - `name` — the behavior in plain language - `category` — one of `happy_path`, `validation`, `auth`, `edge_case`, `error`, `security` - `risk` — `low`, `medium`, or `high` - `given` / `when` / `then` — preconditions, action, expected outcome - `assertions[]` — the specific checks the failing test makes Cover happy paths **and** the categories that specs usually miss: validation, auth, edge cases, error handling. Then build an explicit **risk-scenario set** — at minimum privilege escalation, data leakage, and impersonation, plus any project-relevant threats surfaced in Step 5 — and map each to the cycle(s) that cover it (`covered`, `partial`, or `not_covered`). Surfacing an uncovered high-risk scenario is a feature of this plan, not an omission: list it as `not_covered` so the review makes the gap visible. ## Step 7: Emit the Structured Plan (YAML) Build the machine-readable plan that `/tdd` can later consume. > Full schema and a worked feature/bug example: see `references/plan-template.md`. Top-level shape: ```yaml # Auto-generated TDD Plan # Source: {TICKET_ID or "Manual description"} name: "{DESCRIPTIVE_NAME}" type: feature # feature | bug_fix | refactor description: | {DESCRIPTION_FROM_TICKET_OR_INPUT} context: assumptions: - "{Resolved answer from Step 5}" open_questions: - "{Anything still unanswered}" test_framework: "{jest|vitest|pytest|cargo|go|...}" test_command: "{npm test|pytest|go test ./...|...}" test_file_pattern: "*.test.ts|*_test.py|..." behavior_cycles: - id: BC-001 name: "{Behavior}" category: happy_path # happy_path | validation | auth | edge_case | error | security risk: low # low | medium | high given: "{Preconditions}" when: "{Action}" then: "{Expected outcome}" assertions: - "{Specific check the failing test makes}" risk_scenarios: - id: RS-001 threat: "Privilege escalation" coverage: covered # covered | partial | not_covered covered_by: [BC-003] acceptance_criteria: - "{AC from ticket or derived}" out_of_scope: - "{Explicitly excluded behavior}" ``` ## Step 8: Render the Review HTML Build one self-contained `index.html` the user can open to confirm the plan captures their intent. Reuse the presentation rules below verbatim. **Sections:** - **Header** — `TDD Plan — `, the source ticket/description, detected framework, and counts (behavior cycles, assertions, risk scenarios). Show an estimated reading time. - **Summary / verdict** — what will be built and the overall test posture in a screen's worth of text. - **Behavior cycles** — grouped by category, each showing `given/when/then`, `risk`, and its assertions. - **Risk matrix** — each risk scenario as a row: threat, coverage, and covering cycles. Tint `covered` with `var(--good)` and any `not_covered`/`partial` **high**-risk row with `var(--bad)` so gaps stand out. - **Open questions and assumptions** — the resolved and unresolved items from Step 5. - **Acceptance criteria**. - **Appendix** — out-of-scope items and secondary detail in collapsed `
`. Every string pulled from the ticket, description, or code MUST be HTML-escaped (`&`, `<`, `>`, `"`, `'`) before being written into the page — never interpolate raw content into HTML. Target **6–8 minutes** of reading; keep prose lean and move detail behind `
`. ### Style (single neutral palette) Author against role variables, never raw hex, in one inline `