Dig Up the Hidden Specs Before a Rewrite

After a system rewrite, most of the first bug reports are not "the new feature is broken." They are "it used to work." The list is in a different order. Totals are off by one cent. The previous entry no longer fills in automatically. None of this was in the spec, yet users relied on it every day.

We call these undocumented behaviors hidden specs. In a replacement or major overhaul, if you don't dig them up during requirements, you will rediscover them one bug report at a time after launch.

Why Hidden Specs Disappear

Requirements for a rewrite usually come from the old design documents and feature list. But in a long-lived system, real behavior lives in other places:

• Branches in the code that never made it into the docs (one customer has a different billing cutoff)
• Framework or database defaults (rows come back in primary-key order, string comparison is case-insensitive)
• User habits ("pressing Enter on this screen jumps to the next row")

The new system is built from new documents, so these behaviors vanish even though nobody decided to remove them.

Three Ways to Dig Them Up

1. Record the Current Screens in Use

Ask the people who do the work to run through their main tasks on the old system, and record the screens and steps. Focus less on what they do and more on what they don't have to do:

• Fields that fill themselves (previous values, defaults, autocomplete)
• Default sort order and filters
• Rounding, precision, and display format of calculated values
• Input that silently passes (full-width digits, leading or trailing spaces)

2. Interview Users the Right Way

"What do you need?" won't surface hidden specs, because users aren't aware of them. Ask instead:

• "If X disappeared from this screen, would that be a problem?"
• "Is there anything you do differently at month-end or year-end?"
• "Do you have any workarounds to fit how the system behaves?"

The last one is especially revealing. Manual fixes in a spreadsheet are often built on top of the old system's quirks.

3. Read the Branches in the Old Code

You don't need to read everything. A few targeted searches find a lot:

# Branches on specific values
grep -rnE "if .*(== ?['\"][A-Z0-9]{3,}|customer_id ?==)" src/
# Rounding, ordering, defaults
grep -rnE "round|floor|ceil|ORDER BY|default" src/

A branch on a hard-coded ID or date is almost always a past one-off request. Confirm it while someone still remembers why.

A Keep-or-Drop Decision Table

You don't have to carry every behavior forward. Decide each one with this table and write the result down as a requirement.

The key is recording "drop" as a decision too. When someone says "it used to work" after launch, you can answer right away whether it was removed on purpose or missed. The first needs an announcement; the second is a bug.

Common Mistakes

• Writing requirements only from the old design docs: undocumented changes fall through the cracks
• Interviewing only managers: the people doing the daily work know the details
• Acceptance testing only against the new spec: also compare results with the old system using the same data

Putting It Into Practice With Bugoon

One way to collect hidden specs is to embed the Bugoon widget on the old system's screens. Have staff go through their normal work, and whenever they notice "this fills in by itself" or "we depend on this order," they send an annotated screenshot. Operation steps are recorded automatically, so you can see exactly which sequence produced the behavior.

Sort the reports on the kanban board into Keep / Keep, made explicit / Drop columns, and link the ones you keep to GitHub Issues to track them as requirements for the new system. When an "it used to work" report arrives after launch, you can check it against the same board's records of the old screens.