Skip to main content

⚑ Micro-Spec Documentation

A micro-spec is a document that enables a minimalist approach to documenting small work items (e.g., bug fixes, minor UI changes, configuration updates) requiring minimal effort. Its purpose is to provide sufficient context for implementation and verification while avoiding excessive bureaucracy.

Applicability:

Use for tasks that:

  • Are estimated at less than 1 day of effort.
  • Do not affect multiple system components.
  • Do not require introducing new architectural patterns or technologies.
  • Are obvious and straightforward to implement (e.g., fixing a typo, changing a button color, updating a value in a configuration file).

Authoring Process​

Step 1: Define the Essence of the Change​

Goal: Clearly articulate what exactly needs to be changed or fixed.

Actions:

  • Briefly describe the current (incorrect/suboptimal) state.
  • Clearly describe the desired (correct/target) state.
  • Specify the exact location in the system where the change is required (e.g., file name, screen, line of codeβ€”if obvious).

Step 2: Provide Justification​

Goal: Explain why this change is necessary so any team member can understand its value or necessity.

Actions:

  • State the reason: is this a bug fix, a UX improvement, a client-requested update, compliance with a new guideline, etc.?
  • If it’s a bug fix, briefly describe how to reproduce the issue (or provide a link to the bug tracker ticket).

Step 3: Define Acceptance Criteria​

Goal: Establish objective, verifiable conditions that determine whether the task has been successfully completed.

Actions:

  • Use simple, active voice.
  • Phrase criteria as testable statements. Often, one or two criteria are sufficient.
  • Recommendation: For maximum clarity, you may use simplified EARS syntax (e.g., WHEN... THEN...), though this is optional if the criterion is already unambiguous.

Example of a poor criterion: "Fix the bug."
Example of a good criterion: "After clicking the 'Submit' button, the form no longer freezes and displays the message 'Data successfully submitted'."

Step 4: Validation and Finalization​

Goal: Ensure the micro-spec contains all necessary information and is free of ambiguity.

Actions:

  • Ask yourself: "Can a developer unfamiliar with this task pick up this document and immediately begin implementation?"
  • Ask yourself: "Can a tester (or the developer themselves) unambiguously verify task completion using only these acceptance criteria?"
  • If the answer to both questions is "yes," the specification is ready.

Micro-Spec Document Template​

# Micro-Spec: [Concise and clear task title]

**Current State:** 

[Description of what currently exists and what is wrong.]

**Desired State:** 

[Description of what should exist after the task is implemented.]

**Location of Change:** 

[Specific file, module, screen, URL, etc.β€”where exactly should changes be made?]

## Justification 

[Explanation of why the change is needed. Examples: "Fixing a critical bug preventing users from logging in," "Updating text per the new marketing guidelines," "Changing color to improve accessibility."]

## Testing Strategy

* [Test case]
   * Case description
* [Another test case]
   * Case description

---

## Micro-Spec Quality Checklist

*(Completed by the author after finishing the document)*

| Criterion                                                                                         | Done | Comment |
| ------------------------------------------------------------------------------------------------- | ---- | ------- |
| Specifies the exact location in the system where the change must be made                          | ☐    |         |
| Justification includes business or user value                                                    | ☐    |         |
| All acceptance criteria are phrased in active voice and use EARS (WHEN/IF)                        | ☐    |         |
| Each acceptance criterion is **verifiable** and **unambiguous**                                   | ☐    |         |
| The spec contains no compound requirements (each is split into separate items)                    | ☐    |         |
| Any developer can take this spec and start working on it immediately                             | ☐    |         |