Development Workflow

Development Workflow

This skill implements a strict Test-Driven Development (TDD) workflow.

This project strictly follows TDD practices. All production code MUST be written using the TDD process described below.

Contents

• Contents
• How to use this skill
• Workflow Overview
• Core TDD Principles
• Phase 0: TRIAGE
• Phase 1: PREPARE
• Phase 2: EXECUTE
  • RED-GREEN Step
  • REFACTOR Step
  • VERIFY Step
  • COMMIT Step
  • REPLAN Step
• Phase 3: FINALIZE
  • Per-Task Commits
• Related skills
• Additional Guidelines
• Example TDD Cycle

How to use this skill

Attach this file to your Copilot Chat context, then invoke it when implementing features, fixing bugs, refactoring, or maintaining code. Follow phases in order and stop after TRIAGE when the issue is non-actionable or needs clarification.

Workflow Overview

When assigned a task involving a GitHub issue, follow this workflow:

1. Phase 0: TRIAGE - Understand the issue and determine if action is needed
2. Phase 1: PREPARE - Set up the environment and plan the implementation
3. Phase 2: EXECUTE - Implement the solution using TDD
4. Phase 3: FINALIZE - Squash commits and create the PR

Note: Not all issues require implementation. Phase 0 may result in requesting clarification, confirming the issue is a duplicate, or determining no changes are needed.

Related skills

• RSpec Unit Testing Standards — RSpec rules for test structure, naming, setup patterns, stubbing, and coverage; apply when writing tests during TDD cycles
• TDD Refactor Step — detailed guidance for the REFACTOR step: code smells, techniques, test cleanup, and rubocop integration
• Test Debugging — focused diagnosis for failing or flaky tests
• CI/CD Troubleshooting — workflow for CI failures and environment-specific issues
• PR Readiness Review — final quality gate before opening a pull request
• Command Implementation — scaffolding and reviewing Git::Commands::* classes during implementation
• Facade Implementation — scaffolding and reviewing Git::Repository::* facade methods during implementation

Core TDD Principles

Adhere to the following fundamental principles to ensure high code quality and test coverage:

• Never Write Production Code without a Failing Test
• Bug Fixes Start with Tests: Before fixing any bug, write a failing test that demonstrates the bug and fails in the expected way. Only then fix the code to make the test pass.
• Tests Drive Design: Let the test dictate the API and architecture. If the test is hard to write, the design is likely wrong. When this happens, stop and suggest one or more design alternatives. Offer to stash any current changes and work on the design improvements first before continuing with the original task.
• Write Tests Incrementally: Build tests in small steps, writing just enough to get the next expected failure. For example, first write a test that references a class that doesn't exist (fails), then define the empty class (passes), then extend the test to call a method (fails), then define the method (passes), etc.
• Tests Should Be Atomic: Each test should verify exactly one logical behavior, making failures easy to diagnose and understand.
• Prefer the Simplest Solution: Choose the simplest implementation that could possibly work, even if it seems naive. Complexity should only be added when driven by actual requirements in tests.
• No Implementation in Advance: Only write the code strictly needed to pass the current test.

Phase 0: TRIAGE

The purpose of this phase is to understand what the issue is asking for, investigate the current state of the codebase, and determine whether implementation is needed.

Use this phase when the user references a GitHub issue number (e.g., "Fix issue #999", "Implement #999", "Diagnose issue #999").

1. Fetch the Issue: Use gh issue view #999 to read the full issue content, including description, comments, and labels.

2. Understand the Request: Analyze what is being asked:

   • Is this a bug report? Feature request? Question? Documentation issue?
   • Is the issue clear and actionable, or does it need clarification?
   • Are there reproduction steps or examples provided?

3. Search for Context: Investigate the codebase to understand the area affected:

   • Use grep_search or semantic_search to find relevant code
   • Read related test files to understand existing behavior
   • Check if similar functionality already exists
   • Look for related issues or PRs that might be relevant

4. Reproduce (if applicable): For bug reports:

   • Try to reproduce the issue based on the provided steps
   • Run existing tests to see if they catch the issue
   • Verify the issue still exists in the current codebase

5. Determine Next Steps and Report Findings:

   Option A: Issue needs clarification

   • Comment on the issue using gh issue comment #999 --body "..."
   • Ask specific questions about reproduction steps, expected behavior, or use case
   • STOP here - wait for user/reporter response before proceeding

   Option B: Issue is not actionable (duplicate, won't-fix, already resolved)

   • Comment on the issue explaining your findings
   • Suggest closing the issue or linking to related issues
   • STOP here - no implementation needed

   Option C: Issue is clear and actionable

   • Comment on the issue confirming you understand the request and plan to implement
   • Summarize your understanding and proposed approach
   • Proceed to Phase 1: PREPARE to begin implementation

   Option D: User asked only to diagnose (not implement)

   • Comment on the issue with your diagnostic findings
   • Explain what you discovered (root cause, affected code, potential solutions)
   • STOP here - wait for confirmation to proceed with implementation

GitHub CLI Commands for Phase 0:

• View issue: gh issue view #999
• View with comments: gh issue view #999 --comments
• Comment on issue: gh issue comment #999 --body "Your comment here"
• Search issues: gh issue list --search "keyword"

Phase 1: PREPARE

The purpose of this phase is to ensure the project environment is ready, establish a clean baseline, and create a clear implementation plan before writing any code.

Only proceed to this phase if Phase 0 determined that implementation is needed.

1. Check Uncommitted Changes: If there are any uncommitted changes in the project, ask the user what to do with them before continuing: include them in the current implementation plan, ignore them, or stash them before continuing.
2. Create Feature Branch: Decide the target branch first: main, 5.x, or 4.x per the branch strategy. Then create a new branch from origin/<target-branch> using the naming convention <type>/<short-description> (e.g., fix/issue-999).
3. Verify Project Setup: Run bin/setup to ensure that the project is ready for development.
4. Verify Clean Baseline: Ensure that all existing tests and linters pass by running bundle exec rake default.
5. Analyze and Plan: Understand the requirements, identify edge cases and potential challenges, and break the work into small, isolated tasks. Each task must end in a verifiable state: tests passing, linters clean, its behavior demonstrable on its own. Order the tasks so the sequence proves itself to a reviewer — each commit builds only on work already verified before it. When an effort spans multiple PRs, apply the same rule one level up: slice it into independently releasable PRs, each leaving the gem shippable. Consider what tests will be needed and in what order they should be written.
6. Consider Refactoring: Look for ways to make the implementation of the feature or bug fix easier by performing one or more refactorings. If any are found, suggest them to the user. If the user confirms the refactoring, do the refactoring in a separate TDD process. Only once the refactoring is completed should the current feature or bug fix be worked on.
7. Review Implementation Guidelines: When implementing or modifying git command wrappers, read the "Wrapping a git command" section in CONTRIBUTING.md before proceeding. This ensures consistent API design for method placement, naming, parameters, and output processing.

Phase 2: EXECUTE

The purpose of this phase is to implement each planned task using strict TDD cycles, ensuring every line of production code is driven by a failing test.

Execute each task by repeating the following cycle of steps until all tasks are complete:

1. RED-GREEN: Write failing tests and implement code to make them pass
2. REFACTOR: Improve code quality and design without changing behavior
3. VERIFY: Confirm the task is complete and code meets quality standards
4. COMMIT: Create a commit for the completed task
5. REPLAN: Review the implementation plan, then return to step 1 for the next task

When all tasks are complete, proceed to Phase 3: FINALIZE.

RED-GREEN Step

1. RED Substep

   The purpose of this substep is to write a failing test that you hypothesize will pass with the next incremental bit of task implementation.

   • Write the Test: Write a single, focused, failing test or extend an existing test for the current task.
   • Keep It Minimal: Only write enough of a test to get an expected, failing result (the test should fail for the right reason).
   • Execute and Analyze: Run the specific test file (e.g., bundle exec rspec spec/unit/git/commands/<command>_spec.rb) and analyze the output.
   • Confirm Expected Failure: Confirm it fails with an expected error (e.g., assertion failure or missing definition).
   • Validate: If the test passes without implementation, the test is invalid or the logic already exists. When that happens, revise or skip.

2. GREEN Substep

   The purpose of this substep is to write just enough production code to make the failing test(s) pass.

   • Write Minimal Code: Write the minimum amount of code required to make the test pass.
   • Use Simple Solutions: It is acceptable to use hardcoded values or "quick and dirty" logic here just to get to green, even if this means intentionally writing clearly suboptimal code that you will improve during the REFACTOR step.
   • No Premature Optimization: Do NOT optimize, clean up, or improve code style during GREEN—that work belongs in the REFACTOR step.
   • Execute and Verify: Run the specific test file
     • If the test passes, proceed to the REFACTOR step
     • If the test fails, read the FULL error output including the stack trace. Identify the exact failing line and assertion before modifying any code. Fix only what the error indicates, then re-run. Repeat until the test passes.
   • Rollback on Repeated Failure: If the test cannot be made to pass within 3 attempts, revert all changes from this RED-GREEN cycle, report the issue to the user, and ask for guidance before proceeding.
   • Stay Focused: Do not implement future features or optimizations yet.

REFACTOR Step

The purpose of this step is to improve code quality and design without changing behavior, ensuring the codebase remains clean and maintainable.

You must consider refactoring before starting the next task. Remove duplication, improve variable names, and apply design patterns. Skip this step only if the code is already clean and simple—avoid over-engineering.

For detailed guidance on code smells, refactoring techniques, test cleanup, and rubocop integration, see the TDD Refactor Step skill.

• Generalize the Implementation: Ensure the code solves the general case, not just the specific test case. Replace hardcoded values used to pass the test with actual logic.
• Limit Scope: Do not perform refactorings that affect files outside the immediate scope of the current task. If a broader refactor is needed, add it to the task list during the REPLAN step as a separate task.
• Execute All Tests: Run bundle exec rake default and verify they still pass.
• Verify Test Independence: Verify tests can run independently in any order.
• Confirm Improvement: Ensure the refactoring made the code clearer, simpler, or more maintainable.

VERIFY Step

The purpose of this step is to confirm that the current task is fully complete before moving to the next task.

• Confirm Implementation Complete: Verify all functionality for the task is implemented.
• Run All Tests: Run bundle exec rspec and bundle exec rake test to ensure all tests pass.
• Run Linters: Run bundle exec rubocop and bundle exec rake yard to verify code style and documentation standards.
• Check Code Quality: Confirm the code is clean and well-factored.
• Audit Command Tests (command tasks only): If this task added or modified tests for any Git::Commands::* class, apply the Command Test Conventions skill to every new or changed spec file before committing. Fix any violations found before moving to the COMMIT step.
• Audit Command YARD Docs (command tasks only): If this task added or modified any Git::Commands::* source file, apply the Command YARD Documentation skill to each changed source file. Fix any documentation gaps before committing.
• STOP on Unexpected Failure: If any test unexpectedly fails during VERIFY, STOP immediately and report the failure to the user. Do not attempt to fix the failure without first explaining what went wrong and getting confirmation to proceed.