## Engineering terms: development workflow

From Vibe Coding 101 (https://vibe-coding-101.brighteng.org/). When a request describes one of these problems, use the named technique, say its name, and run its check. Each term's page has the full entry and a prompt.

- **test-driven development**: Let one failing example drive the next implementation. Use when: You can describe the behavior before writing it. Do: Choose one observable example. Run red, green, then refactor. Check that red failed for the missing behavior. Avoid: A syntax error is mistaken for proof that the test detects the missing behavior. Worked example: https://vibe-coding-101.brighteng.org/examples/tdd.md
- **refactoring**: Change internal structure while preserving observable behavior. Use when: A working implementation is becoming hard to change. Do: Name the behavior to preserve and the scope to improve. Check those behaviors before and after. Avoid: Changing assertions to accept a behavior change conceals a regression.
- **minimal reproduction**: The smallest repeatable case that still shows the bug. Use when: A bug report says something is broken but cannot show how. Do: Remove unrelated setup until the failure is small and repeatable. Check it from a clean starting state. Avoid: Removing the condition that causes the failure produces a different test case. Worked example: https://vibe-coding-101.brighteng.org/examples/repro.md
- **root cause analysis**: Find the mechanism that produces the failure. Use when: Fixes keep moving the same bug to another place. Do: Trace the input across boundaries. Change one suspected cause. Check whether the original failure changes as predicted. Avoid: Several simultaneous changes hide which explanation was correct.
- **git worktree**: A separate checkout and index sharing the same Git repository. Use when: You need another branch without disturbing unfinished edits. Do: Create the checkout and identify shared ports and data. Check git status in both directories. Avoid: A separate directory still connects to the same database.
- **verification**: Check the claimed result against fresh evidence. Use when: The agent says a fix is done, but only describes its edits. Do: Choose the check that would expose the failure. Run it after the final edit and report its actual outcome. Avoid: An earlier passing result is reused after further edits.
- **reverse engineering**: Recover a behavioral specification from an existing system. Use when: You need compatibility with an existing product or undocumented module. Do: Record representative interactions and turn the observations into executable examples. Avoid: Assuming an unobserved edge case behaves like the happy path.
- **characterization test**: Record the behavior an existing implementation exhibits. Use when: You need to change legacy code whose intended behavior is poorly documented. Do: Capture representative inputs and outputs; label known defects separately from behavior to preserve. Avoid: Freezing incidental output so every harmless edit breaks the suite.
- **spike**: A short investigation answers one technical unknown. Use when: You cannot choose an approach until an integration or performance assumption is tested. Do: Name the question, time limit, and evidence needed. Record what the experiment does not prove. Avoid: Treating a successful toy example as proof of production readiness.
- **walking skeleton**: A minimal working path connects the application’s essential layers. Use when: The UI, backend, persistence, and deployment have never worked together. Do: Implement one small persistent action and deploy it to an isolated preview. Avoid: Mocking away the integration the skeleton is supposed to establish.
- **vertical slice**: Implement one usable behavior across the layers it requires. Use when: Work is divided into complete UI and backend layers with nothing usable yet. Do: Choose one user outcome and trace it through every required layer. Avoid: Calling a collection of disconnected components a finished slice.
- **strangler fig**: Replace an existing system incrementally by routing selected behavior to a new implementation. Use when: A large rewrite needs smaller, reversible releases. Do: Move one boundary at a time, compare behavior, and define when the old path will be removed. Avoid: Keeping two implementations indefinitely with no owner for their divergence.
- **executable specification**: An executable specification makes requirements checkable. Use when: The agent keeps filling gaps with different interpretations. Do: Write observable examples and constraints before implementing the uncertain behavior. Avoid: A document describes the intended behavior but no check exercises it.
- **behaviour-driven development**: Describe behavior through concrete examples shared by developers and domain experts. Use when: Product rules are understood differently by different contributors. Do: Choose examples with observable outcomes, including rejection and boundary cases. Avoid: Treating scenario syntax alone as proof that the requirement is understood.
- **ubiquitous language**: Use a shared domain vocabulary in requirements, code, and conversations. Use when: Order, booking, and reservation refer to the same thing in different files. Do: Define the domain terms and map existing names before making scoped renames. Avoid: Renaming distinct business concepts into one word because they look similar.
- **YAGNI**: Avoid implementing capabilities before a current requirement justifies them. Use when: The proposed change adds extension points and configuration with no current consumer. Do: Separate required behavior from hypothetical future variation and implement the required part. Avoid: Calling necessary error handling or access checks speculative work.
- **contract-first design**: Define an interface before implementing its producers and consumers. Use when: Frontend and backend implementations disagree on request or response formats. Do: Agree on a small contract and run checks from both sides of the boundary. Avoid: Changing the producer’s contract without checking existing consumers.
- **partial staging**: Partial staging selects changes within a file for the next Git commit. Use when: A working directory contains an unrelated experiment beside a completed fix. Do: Review the staged diff independently from the remaining working-tree diff. Avoid: Running a later blanket add that includes the previously excluded changes.