🎯 Learning Objectives
By the end of this lesson, you will:
- Identify the three types of documentation contradictions
- Apply three cross-referencing techniques during a review
- Distinguish between a contradiction and a gap
- Write a review comment that resolves a contradiction productively
🔄 The Problem with Long Documents
Large specs have a dirty secret: they contradict themselves.
Not because the author is careless. It happens because:
- Documents evolve over time. Old sections aren't always updated.
- Multiple authors work on different sections without coordinating.
- Decisions are made in meetings and never updated in the spec.
- A concept is described once at the start and again in a different way later.
A developer reading section 7 may not remember what section 2 said. Their implementation follows what they read last. The tester checks against the original requirements. And suddenly: a bug that "isn't really a bug" — it's a conflicting specification.
🔍 The 3 Types of Contradictions
Type 1: Internal Contradiction (Within a Document)
The same document says two different things in different places.
Example:
- Section 2: "A user can have a maximum of 5 saved addresses."
- Section 9: "Users may save up to 10 addresses."
Impact: Developer picks one number. Tester tests against the other. Instant "bug".
Type 2: Cross-Document Contradiction
Two documents in the project contradict each other.
Example:
- PRD: "Login is available via email and Google SSO."
- Tech Spec: "Authentication is handled by email/password only. SSO is out of scope."
Impact: Feature gets built without SSO. PM is surprised at release.
Type 3: Document vs. Reality Contradiction
A document says something that contradicts what was actually implemented or decided in a meeting.
Example:
- Spec says: "Email is required."
- The team decided in last week's sprint planning: "Email is optional for guest checkout."
Impact: Developer builds the new behavior correctly but it doesn't match the spec. Tester raises a "bug" against old spec. Confusion and wasted time.
🛠️ Technique 1: Forward Reading
Read the document from beginning to end, noting every defined rule or stated fact.
Create a mental (or actual) list:
- "Section 2 says: max 5 addresses"
- "Section 9 says: max 10 addresses" 🚨
Forward reading is simple but effective. Contradictions often appear between an early "overview" section and a later "detailed" section.
🛠️ Technique 2: Back-Reference Checking
When you read a rule or a constraint, search backward for any earlier mention of the same topic.
Useful for:
- Numbers and limits (max, min, count)
- Defined terms (is "user" always the same kind of user?)
- Status transitions (can a "cancelled" order be reactivated?)
🛠️ Technique 3: Cross-Document Comparison
Keep the relevant documents open side-by-side. After reviewing each one, do a targeted comparison on key topics:
| Topic to compare | Documents to check |
|---|---|
| Authentication method | PRD ↔ Tech Spec |
| User roles and permissions | BRD ↔ PRD ↔ User Stories |
| Data validation rules | Tech Spec ↔ Figma ↔ User Stories |
| Error messages | Tech Spec ↔ Figma ↔ UX copy |
📝 How to Report a Contradiction
Don't just say "these two things are different." Give the author what they need to resolve it.
Weak comment: "Section 2 and Section 9 contradict each other."
Strong comment:
"I found a conflict: Section 2 (line 47) says max 5 saved addresses; Section 9 (line 203) says max 10. Which is the intended limit? I'll hold off writing test cases for this until it's clarified."
The strong comment includes:
- Where each conflicting statement is
- What the specific conflict is
- What you need (a decision)
- What you're waiting for (no test cases until resolved)
⚠️ Contradiction vs. Gap
It's important to distinguish:
| Type | Definition | Example |
|---|---|---|
| Contradiction | Two things that conflict | "Max 5" vs "Max 10" |
| Gap | Something not mentioned at all | No spec for "what if the save fails?" |
Both are problems. But they're solved differently:
- Contradiction: someone must choose one answer
- Gap: someone must provide an answer
🌍 Real-World Example
Document 1 (BRD): "The system must comply with GDPR. Users can request deletion of their data."
Document 2 (Tech Spec): "User records are soft-deleted (marked inactive) but not removed from the database."
Is this a contradiction? Yes — GDPR data deletion is legally required to be permanent, not just a soft-delete flag.
Review comment:
"There's a potential conflict between the GDPR compliance requirement in the BRD (hard delete) and the Tech Spec's soft-delete approach. Could this be reviewed with the legal/compliance team before development? GDPR Article 17 requires erasure, not just deactivation."
💡 Pro Tips
💡 Tip 1: Terminology inconsistency is often a warning sign of a deeper contradiction. If a document calls the same thing "user", "customer", "account holder", and "member" — clarify the terms first.
💡 Tip 2: Numbers are your best friends for finding contradictions. Scan the document for every number (limits, timeouts, counts, durations) and verify each one appears consistently.
💡 Tip 3: The most dangerous contradictions are between documents that are maintained by different teams. Cross-team docs rarely stay in sync automatically.
📋 Summary
- 3 types of contradictions: internal (within a doc), cross-document, document vs. reality
- 3 techniques: forward reading, back-reference checking, cross-document comparison
- Reporting: specify location, quote the conflict, ask for a decision
- Contradiction vs. gap: different problems, different solutions
Module 2 complete! You can now hunt down the logic bugs hiding in plain text. Module 3 takes us into the visual world of mockups and design. 🎨