Reverse ACDD

Retrofitting existing code with proper acceptance criteria, tests, and documentation.

Most codebases weren't built with ACDD. You have working code, but it lacks proper tests, clear acceptance criteria, or comprehensive documentation. Reverse ACDD is the process of working backwards—from implementation to proper specification.

The Natural Language Process

With fspec, you guide your AI through reverse ACDD using conversational prompts. Here's the journey:

Step 1: Discover What Exists

Start by asking your AI to understand the existing code:

"Analyze the UserAuthentication module. What does it do? What are its main responsibilities?"

"Look at the payment processing code. What are all the different paths through this logic?"

"Read through the order management system and identify all the business rules."

The AI will explore the codebase and give you a clear picture of what exists.

Step 2: Example Mapping

Once you understand what's there, create an example map:

"Create an example map for the user authentication flow. Include:
- Happy path examples
- Edge cases you can find in the code
- Error scenarios the code handles"

"Map out concrete examples for the payment processing. What different payment types are supported? What validations exist?"

Step 3: Generate Scenarios

Transform the examples into proper scenarios:

"From the example map, generate Given-When-Then scenarios for user authentication.
Create a story in fspec and attach these scenarios."

"Convert the payment processing examples into executable scenarios.
Each scenario should be testable."

Step 4: Write Tests

Now implement tests for those scenarios:

"Write tests for each authentication scenario we mapped.
The code already exists—write tests that verify it works correctly."

"Implement tests for the payment processing scenarios.
Start with the happy path, then cover edge cases."

Step 5: Refactor Safely

With tests in place, you can safely improve the code:

"Now that we have tests, refactor the authentication code to be more readable.
Keep the tests passing."

"The payment processing has some duplication.
Extract common logic while maintaining test coverage."

Step 6: Document Properly

Finally, create comprehensive documentation:

"Document the authentication module. Explain:
- What it does
- How to use it
- The acceptance criteria we discovered
- Common gotchas from the example map"

"Create API documentation for the payment processing.
Include examples from our scenarios."

Making Decisions During Reverse ACDD

The process isn't always linear. You'll need to make decisions:

When Code Behavior is Unclear

"This validation logic seems inconsistent. Should passwords allow Unicode characters?
Let's create a checkpoint before we investigate."

"Create a question in the example map: 'Should emails be case-sensitive for login?'
We need to decide this before writing tests."

When You Find Bugs

"This looks like a bug—the code allows negative quantities.
Create a bug story in fspec to track this."

"The password validation has a logic error. Should we fix it now or later?
Let's discuss the risk."

When Tests Reveal Missing Coverage

"We've covered happy paths, but what about concurrent logins?
Add scenarios for race conditions."

"The example map shows we're missing tests for expired tokens.
Let's add those scenarios."

The Natural Language Workflow

Here's how a complete reverse ACDD session might look:

YOU: "Let's do reverse ACDD on the shopping cart module."

AI: "I'll start by analyzing the code..."

YOU: "Create an example map for adding items to the cart.
What edge cases exist in the current code?"

AI: "I found these scenarios: adding first item, adding duplicate items,
adding when cart is full, adding invalid items..."

YOU: "Good. Create a story in fspec called 'Shopping Cart - Add Items'
and attach that example map as a markdown document with a mermaid diagram."

AI: "Story created and checkpoint saved."

YOU: "Generate Given-When-Then scenarios from the example map."

AI: "I've created 8 scenarios covering all the cases we found..."

YOU: "Implement tests for these scenarios. Start with the happy path."

AI: "Tests written and passing! The existing code handles all cases correctly."

YOU: "Create another checkpoint. Now let's refactor to improve readability."

AI: "Checkpoint saved. What improvements should we make?"

YOU: "The item validation logic is duplicated. Extract it to a helper method."

AI: "Refactored. All tests still green!"

YOU: "Perfect. Document this module with the acceptance criteria we discovered."

Key Principles

Trust the Existing Code (At First)

The code is in production and working. Your first goal is to understand and verify it, not fix it:

"Write tests that prove the current code works as designed.
Don't change behavior yet—just document it with tests."

Use Checkpoints Liberally

Reverse ACDD is exploratory. Create checkpoints before major steps:

"Create a checkpoint before we start testing the payment module."

"Save a checkpoint now that all authentication tests are passing."

Let Discovery Drive Testing

Don't write tests for what you think the code should do. Write tests for what it actually does:

"This validation accepts both email and username.
Write tests for both, even if it seems redundant."

"The code has special handling for admin users.
Add scenarios for that—it's part of the actual behavior."

Document Decisions and Questions

The example map should capture both:

What the code does (green/red examples)
What's unclear (yellow questions)

"Add to the example map: QUESTION - Should we validate email format on registration or just on login?"

"Document in the story: DECISION - We allow Unicode in usernames because that's current behavior."

When to Use Reverse ACDD

Reverse ACDD is perfect for:

Legacy codebases - No tests, no docs, just code
Third-party code - Understanding libraries or inherited systems
Before refactoring - Lock in current behavior before changes
Onboarding - Learning an unfamiliar codebase through test-driven exploration
Compliance - Creating documentation and evidence for audits

Next Steps

Once you've completed reverse ACDD on a module:

Keep tests green - Maintain the test suite as documentation
Use checkpoints - Before any changes, create a checkpoint
Switch to forward ACDD - New features follow full ACDD from the start
Share knowledge - The tests and docs help others understand the system

The goal isn't perfection—it's understanding. Reverse ACDD gives you the confidence to work with existing code safely.

Git Checkpoints Coverage Tracking