iTranslated by AI
Minimizing Misalignment and Rework: 4 Techniques to Clarify Specifications in Agile Development
This article is a post for Day 20 of the Developer Productivity Community D-Plus🐬 Advent Calendar 2025.
Yesterday's article for Day 19 was The Essence of Agile Development: What is "Agree to Disagree"? by Shinya Hiroishi-san!
Introduction
"The specifications were supposed to be set, but once we started implementing, we realized there was a gap with the Product Manager's understanding, resulting in rework."
As an engineer, you've likely experienced this at least once. Misunderstandings, rework, and missing requirements that come to light toward the end of implementation. Many of these cases are driven by the ambiguity of specifications.
Just as TDD (Test-Driven Development) drives development starting from tests, Specification-Driven Development (SDD) drives development starting from specifications. In recent years, SDD has been gaining attention. There are significant benefits to clarifying specifications, such as AI-assisted specification-based planning.
However, I felt that it is difficult for this to function if specifications remain ambiguous or if the team members' understanding of the specifications is not aligned. To increase the effectiveness of SDD, it is essential that the underlying specifications are clear and that there is a common understanding among members.
In this article, I will introduce four methods practiced by a Scrum team of 8 members for a B2B SaaS product during two projects—each lasting about two months—to reduce specification ambiguity before the design phase.
Overview of the 4 Methods
The four methods I am about to introduce are implemented along the project's timeline.
-
- Example Mapping: Conducted at the beginning of the project, before estimation.
-
- Specification Review Meeting: Conducted after estimation, when the draft design is completed.
-
- Question Box (Simple ADR): Operated continuously from before estimation through the development period.
-
- Design Consensus Building: Conducted during the design phase.
① Example Mapping
Misunderstandings were occurring due to the scope not being clear. We either over-implemented or discovered implementation gaps during sprint reviews. It’s always painful to delete code that never saw the light of day, no matter how many times you experience it. To prevent this, we introduced Example Mapping.
Example Mapping is one of the techniques for requirement definition and specification clarification in agile development. It deepens the entire team's understanding of specifications by categorizing and organizing User Stories, Rules, Examples, and Questions.
At the beginning of the project, before the estimation phase, the Product Manager (PdM), engineers, QA, and designers gathered to perform Example Mapping for the specifications of the GitHub Projects integration. We used FigJam as our tool.
Sticky notes divided into Stories, Activities, Steps, Details (P0, P1, P2), Rules, Examples, and Questions
We were able to identify concrete use cases and edge cases for the complex specifications of the entire project. By using FigJam, we could brainstorm while pasting screenshots and links, which made the discussion lively.
The entire team was able to have a common understanding of the specifications, reducing rework in subsequent processes.
On the other hand, when implementing Example Mapping, it takes some effort to draw out proactive comments from all members. As a facilitator, I encouraged active discussion by appropriately calling on people, asking things like, "Does [Name], who is familiar with the backend, have any concerns about this part?" or "Is there anything you're curious about from a QA perspective?"
Also, I made sure to clarify all next actions. Decide what to do and by when, such as creating items in the product backlog or adding descriptions, and then wrap up. If you neglect this, even though you had a good discussion, it will be left alone and won't be referenced during implementation.
It is crucial to build awareness and a culture where everyone, including the PdM, participates proactively. Simply introducing the method is not enough; it's important that all members are actively involved.
Please also refer to this presentation material from D-Plus Tokyo #19.
② Specification Review Meeting
We sometimes noticed gaps in our understanding of specifications only after starting implementation. For example, to display elements from a design on a screen, processing that combines two models might be necessary, but we would implement them separately at the model level, requiring us to fix the implementation later. This is a common scenario, right? To prevent this, we introduced Specification Review Meetings.
When the draft design was completed, we held a session where the PdM, engineers, QA, and designers gathered to write down points of concern as comments in Figma.
Writing comments on Figma designs
Since Figma clearly shows designs and flowcharts, discussing based on Figma allowed us to notice discussion points that we couldn't catch through text-based product backlog creation or oral discussions.
Also, by discussing while moving prototypes on the design, we noticed omissions in user journeys and operation flows. Having a concrete artifact like a design makes it easier for insights to emerge from an engineering perspective.
However, we weren't always able to identify all the detailed designs at this stage. To be honest, there was a part of me that thought someone else on the team would figure it out. This led to the need for "④ Design Consensus Building" later on.
Here as well, it is crucial to build an awareness and culture where everyone, including the PdM and designers, participates proactively.
③ Question Box (Simple ADR)
Cases where discussions took place on Slack or orally without being reflected in the product backlog were occurring frequently. As a result, we faced issues such as being troubled by unclear specifications during QA or being unable to look back at the history of decision-making later.
During the development period, we created a system to manage who currently has the ball and what was decided using a Notion database. It’s not as heavy as an ADR (Architecture Decision Record), but a lighter format called a "Question Box."
We refined the granularity of statuses while operating it. We clarified ownership with statuses like "Engineer responding" or "PdM responding." We also clarified next actions for completion statuses, such as "Product backlog item created," "Response completed," and "No action required."
Visualizing questions and their statuses in a Notion database
Omissions in reflecting user stories and cases of missed ownership decreased, reducing rework.
As a tip for making it work asynchronously, I felt that creating it in Notion was effective. You can freely write screenshots, screen recordings, notes, and more. While the ADR format raises the hurdle for writing, the light "Question Box" format made it possible to write. Furthermore, by leaving the context and background in Notion, people who don't know the background can trace the history later. Context is something that can be lost after a few years, so the light format made it easy to leave the background casually.
However, it was always a battle against it becoming a mere formality. In the daily stand-up, we included an agenda item to always check by filtering for items that are not "Done." This prevented the process from becoming obsolete.
Also, some said, "I'm not sure if I should write it in the Question Box." Therefore, we made it a rule to always record it if it leads to a discussion because it cannot be immediately added or corrected in the product backlog. There were even cases where someone who noticed a discussion on Slack or in a meeting would create an item, even if they weren't the one who proposed it.
④ Design Consensus Building
Due to resource constraints, there were cases where task owners would independently design and start development. As a result, resolution and understanding differed among members, and design policies became inconsistent. There was also a risk that development would stop if the owner was absent.
Therefore, we introduced a process aimed at balancing efficiency and consensus building regarding design and sharing. Specifically, we proceeded in four steps:
- One or two people design and record it in Notion or FigJam, leaving comments on points of concern.
- Share the materials with the whole team in advance.
- After sharing the materials, hold a sharing session for refinement.
- Based on the results, save it as a Markdown document on GitHub.
The design sharing sessions became meaningful discussions because people participated after reading the materials and adding comments in advance.
It also became easier to invite specialists from outside the team. By sharing materials in advance and minimizing meeting time, we could reduce the load on specialists' resources. This is because we could request them to check the materials beforehand and provide feedback.
The Markdown documents saved on GitHub also functioned as a foundation for Specification-Driven Development. By having an agent AI read the design documents when planning, we were able to improve the accuracy of plans and implementations. Having specifications that the whole team has a common understanding of written down allows us to instruct the AI correctly.
Since one or two people create the draft, there were times when things were significantly overturned in the sharing session with people saying, "Isn't that different?" However, that is only possible because there is a draft. Instead of aiming for a perfect design from the start, we achieved both efficiency and consensus building by having a small group create a draft, discussing it, and reaching an agreement as a team.
Points to Consider When Putting These into Practice
Lastly, here are three things to keep in mind when introducing these methods.
Don't just do it once and be done
Example Mapping and Specification Review Meetings are conducted at the beginning of a project, but as development progresses, members' understanding improves and new points of discussion will emerge. If you don't repeat them for a long time just because you did them once, gaps will appear and the effectiveness will diminish.
I recommend dividing the project into milestones and repeating Example Mapping and Specification Review Meetings at the beginning of each milestone.
Regarding milestone division, please refer to this previous post:
Becoming a mere formality is inevitable
The Question Box will have fewer entries if it is not used actively. Design sharing sessions will be skipped when things get busy.
Becoming a mere formality is the fate of any operational process. It's not enough to just build the system; you need the awareness to maintain it. Continuously work to prevent it from becoming obsolete through measures like following up during fixed-point observations at daily stand-ups and encouraging people to create entries when discussions occur on Slack.
This presentation material from the D-Plus Tokyo 1st Anniversary Gratitude Festival is also a good reference.
Culture comes before methodology
These methods will not function unless there is a culture where everyone participates proactively. Even if you introduce the methodology, if members do not participate, it will just be a shell.
It is necessary to nurture a sense of ownership through steady efforts—continuously encouraging comments and entries, and repeatedly communicating the importance of having a common understanding among all team members. Methodology sits on top of culture.
Summary
Left unchecked, ambiguity in specifications causes misunderstandings and rework in the final stages. To drive development based on specifications, the specifications must first be clear.
Therefore, we practiced four methods up until the design phase:
-
- Example Mapping: Conducted at the beginning of the project, before estimation
-
- Specification Review Meeting: Conducted after estimation, when the draft design is completed
-
- Question Box (Simple ADR): Operated continuously from before estimation through the development period
-
- Design Consensus Building: Conducted during the design phase
When proceeding with projects with high uncertainty, please give these methods a try. And instead of just doing it once, keep in mind to create a system that allows for continuous rotation.
Tomorrow's post will be "Communicate via documents rather than reading between the lines. Share the 'history' of the organization and connect it to development productivity" by Kennie-san!
Discussion