Case study / ClockUp
See the system applied to a real product.
ClockUp is a real-world example of how product decisions can move from an initial idea through structured documentation to implementation-ready specifications.
02 / The product
ClockUp turns the workday into something employees can understand and track.
ClockUp is a gamified employee work-hours tracking platform designed to help employees understand their daily work time, track progress toward a 9-hour goal, and stay consistent through progress visibility and positive reinforcement.
09h 00m
Daily work goal
Instead of functioning as a traditional attendance system, ClockUp was designed around personal progress, consistency, and positive reinforcement.
03 / The documentation system
One product. Ten specifications. One connected system.
ClockUp was not treated as one giant specification. Product intent, functionality, rules, behavior, design, data, communication, architecture, implementation order, and AI behavior were separated into distinct layers.
Product
Engineering
04 / Product evolution
The specification changed as the product became clearer.
The original ClockUp specification established the initial product model. Later decisions refined the dashboard, points, Time Credits, overtime behavior, and redemption architecture.
Dashboard
Multiple dashboard modules, including Today's Work, My Progress, Time Credits, Team & Standing, History & Records, Attention, and Identity.
Today, Time Credits, Recent Activity.
The dashboard was simplified from multiple analytical modules into a more focused daily experience.
Time Credits
Present only in limited form in the original product material.
Time Credits became a major product concept: work beyond 9h → bank Time Credits → redeem on a short day.
Time Credits were a later evolution, not an original pillar of the product.
Points
9h = 100 points, with additional overtime increments earning additional points, capped by the original business rules.
Later discussions redesigned the points model.
The reward model changed during product evolution.
Overtime
The original specification included overtime-related points.
9h shift → overtime opt-in → declared ceiling → actual overtime worked becomes bankable.
Proposed / awaiting review — not yet confirmed as approved behavior.
Missed Clock Out
Missed Clock Out → recovery on next login → submit missing Clock Out time → edited attendance.
A later proposal retires the old runaway-timer/recovery behavior under the proposed 9-hour cap.
The documentation does not establish which behavior is final. The conflict is shown, not resolved.
05 / Complete trace
Follow one decision all the way to implementation.
Clock In exists at every layer of the system, but each document answers a different question.
Feature: Clock In
PRD
Why
Clock In exists as part of the product's goal of helping employees track and complete their required workday.
FSD
What
Clock In starts an employee's working session and enables live working-time tracking.
BRD
Rules
- Can happen once per working day
- Requires GPS verification
- Requires the employee to be inside the configured office geofence
- Stores server timestamp and location-related verification data
UFD
Behavior
DSD
Experience
The Clock In interaction should provide clear feedback, update the working state, and start the live timer without making the interface feel like surveillance.
DDD
Data
Clock In creates and updates attendance data, including relevant timestamps and location verification information.
ASD
Communication
POST /api/v1/attendance/clock-in
TAD
Structure
Business logic should not live inside the UI or directly inside the route handler.
DR
Order
Clock In implementation becomes a development task with dependencies and acceptance criteria, ordered relative to the rest of the attendance system.
AI Instructions
Agent behavior
The AI agent must implement the documented Clock In behavior without inventing missing product or business decisions.
The traceability model
This is a conceptual model of how a decision can be traced across the system. Not every layer of Clock In carries an explicit ID in the ClockUp source material — the chain illustrates the principle, not a literal ID lookup.
06 / Specification gap
When the documentation stops, implementation should stop too.
AI should not silently invent a product decision just because implementation needs an answer.
Specification gap
Feature
Attendance / Missed Clock Out
The original documentation defines a Missed Clock Out recovery flow.
A later proposal introduces a 9-hour cap and a different auto-complete model.
The documentation does not establish which behavior should be treated as the final approved behavior.
Implementation paused.
Decision required.
Illustrative decision
- A. Use the original recovery behavior
- B. Adopt the proposed capped behavior
- C. Other decision
AI reports the ambiguity instead of silently choosing.
07 / Human + AI
AI implements decisions. Humans own important decisions.
Human
- Product decisions
- Scope
- Business rules
- Important UX decisions
- Data decisions
- API contracts
- Architecture
- Implementation priorities
- Specification changes
- Approvals
AI
- Defined implementation
- Boilerplate
- Interface behavior within specification
- Data structures within specification
- API implementation within contract
- Tests
- Refactoring
- Repetitive implementation
- Verification
- Reporting specification gaps
08 / The takeaway
ClockUp is the example. The system is the point.
A product does not become implementation-ready because an AI agent is capable of writing code. It becomes implementation-ready when important decisions have been made explicit, documented, connected, and verified.
↺ Review feeds back into Documentation.
“The goal is not to remove humans from implementation. The goal is to remove unnecessary ambiguity from implementation.”