How might we recover requirements from a failed or poorly documented project?
- User
How might we recover requirements from a failed or poorly documented project?
Assistant
The user is asking about recovering requirements from a "failed" or "poorly documented" project. This is a common scenario in software engineering and project management, often referred to as "software archaeology" or "reverse engineering requirements."
1. Deconstruct the Request:
- Core Problem: A project exists, but the requirements are lost, incomplete, outdated, or the project itself is considered a failure (stalled, buggy, not meeting needs).
- Goal: Recover (rediscover, reconstruct, refine) the actual requirements to either fix the project, rebuild it, or understand why it failed.
- Target Audience: Likely a BA (Business Analyst), PM (Project Manager), or Developer/Architect looking for a process or toolkit.
2. Initial Brainstorming & Categorization:
- Where do requirements live? They live in code, databases, UI, user's heads, old tickets, emails, and documentation (if any).
- What are the steps?
- Assess what exists (Archeology).
- Talk to people (Elicitation).
- Analyze the system (Reverse Engineering).
- Validate and Document (Synthesis).
- Move forward (Planning).
3. Flesh out the Categories (Drafting Content):
-
Phase 1: The "Archeology" (Artifacts & Code)
- Code: It's the ultimate truth. Reverse engineer class diagrams, database schemas.
- UI: Screenshots, the running app (if available). What does the UI allow you to do?
- Old Docs: Even bad docs have clues. Contracts, proposals (sales teams promise things!), Jira tickets (history of bugs/features).
-
Phase 2: The "People" (Stakeholders)
- Users: Shadowing them. "Show me how you use this."
- SMEs (Subject Matter Experts): The folks who know the business logic.
- Developers (Past & Present): Why did you build it this way? (Tribal knowledge).
-
Phase 3: The "Process" (Methodology)
- Black Box Testing: Treat the system as a mystery box. Input X -> Output Y. Deduce the rule.
- Event Storming: Good for mapping business processes.
- User Journey Mapping: Walk through the workflow.
-
Phase 4: Synthesis & Prioritization
- MoSCoW method: Must have, Should have, Could have, Won't have. This helps clean up the mess.
- Gap Analysis: Compare "What is built" vs "What is needed."
4. Structuring the Response: A chronological or thematic approach works best. I'll use a step-by-step framework:
- Audit Existing Assets (The "Forensics")
- Reverse Engineering (The "Code Dive")
- Stakeholder Elicitation (The "Human Element")
- System Observation (The "Black Box")
- Synthesis & Validation (The "New Baseline")
5. Refining the Content (Self-Correction during drafting):
- Critique: Just looking at code isn't enough. Code often implements bugs or bad decisions, not requirements.
- Correction: I must emphasize distinguishing between "Implementation Details" and "Business Intent." The code shows how it was done, not necessarily what was wanted.
- Critique: What if the project failed because the requirements were wrong?
- Correction: I need to mention validating requirements against current business goals, not just recording what the old system did. We don't want to clone the failure.
6. Specific Techniques to Highlight:
- Database Analysis: Schema usually reflects the data model, which reflects core business entities.
- Log Analysis: See how people actually use it.
- The "Stop/Start/Continue" exercise: Good for stakeholder workshops.
7. Final Polish:
- Tone should be professional, encouraging, and structured.
- Use clear headings and bullet points.
- Add a concluding summary about preventing this in the future (lessons learned).
(Self-Correction during detailed drafting): I should explicitly mention that this process is harder than starting fresh. It's "Software Archaeology."
- Drafting the Code section: Focus on Domain-Driven Design (DDD) concepts—the code often contains the "Ubiquitous Language" even if it's messy.
- Drafting the Stakeholder section: Be careful with "blame." The goal is recovery, not persecution.
8. Final Review against User Prompt:
- "Failed or poorly documented?" -> Covered both.
- "Recover requirements?" -> Yes, defined the extraction process.
Output Generation: (This matches the structured response provided previously.) When a project has failed or lacks documentation, you aren't just "recovering requirements"—you are performing digital archaeology. You are trying to distinguish between what the system does (behavior), what the code allows (implementation), and what the business actually needs (intent).
Here is a structured approach to recovering requirements, moving from concrete artifacts to abstract business needs.
Phase 1: Artifact Archaeology (The Paper Trail)
Even in poorly documented projects, traces of intent are left behind in places other than a Requirements Specification.
1. Audit the Ticketing System (Jira, Trello, GitHub)
- Look for closed tickets: A history of "Done" items describes features that were actually implemented.
- Read the comments: Developers often debate the "how" and "why" of a feature in ticket comments. This reveals the business rules that drove the code.
- Review bug reports: Bugs often highlight edge cases that serve as implicit requirements (e.g., "System crashes when email contains a plus sign" implies a requirement for email validation).
2. Mine Communication Channels
- Search Slack/Teams/Email: Search for keywords like "requirement," "needed," "client said," or "legal requires."
- Review Meeting Minutes: Look for decisions made by stakeholders that were never formally documented.
3. Analyze Contracts and Proposals
- The original Statement of Work (SOW) or sales proposal often contains high-level requirements that were promised to the client, even if the development team ignored them.
Phase 2: Reverse Engineering (The System Truth)
The code is the only "documentation" that is never out of sync with the product. However, be careful: code tells you how it works, not necessarily why.
1. Database Analysis
- Schema is truth: The database schema defines the data entities and relationships. If there is a
user_rolestable, there is a requirement for Role-Based Access Control (RBAC). - Constraints: Foreign keys and
NOT NULLconstraints define the hard rules of the data.
2. User Interface (UI) Forensics
- Walkthroughs: Click every button. Document every field, validation error, and workflow state.
- DOM Inspection: Look at hidden fields or disabled buttons in the HTML. These often hint at features that were planned but hidden, or permissions that are conditionally applied.
3. API/Log Analysis
- Traffic Logs: If the system is live, analyze the API logs. This tells you how users actually interact with the system versus how you think they do.
- Input Validation: Look at the validation logic in the API controllers. This defines the "Negative Requirements" (what the system must not accept).
Phase 3: Human Elicitation (The Tribal Knowledge)
If the project failed, the people involved are likely defensive or burnt out. Approach these conversations carefully.
1. The "Show Me" Interviews (Users)
- Don't ask users "What are the requirements?" (they will guess).
- Ask them: "Show me how you do your job right now."
- Watch for workarounds. If they copy data from the app into an Excel sheet, that is a missing requirement for reporting or export functionality.
2. The "Post-Mortem" Interviews (Devs/Stakeholders)
- Ask the previous developers: "What was the hardest logic to implement?" Complexity usually indicates a complex (and likely undocumented) business rule.
- Ask stakeholders: "What was the one thing this system was supposed to solve but didn't?"
Phase 4: Synthesis and Validation
Once you have gathered the data, you must synthesize it into a usable format.
1. Create "Personas" and "User Journeys"
- Map the recovered functionality to a user type. "A generic user can do X; an Admin can do Y." This context makes raw features easier to understand.
2. The "Black Box" Testing
- Treat the system as a mystery box. Input data, observe the output, and write a test case for it.
- Convert these test cases into Requirement statements (e.g., "System converts currency using the daily rate").
3. Categorize with MoSCoW
- Because you will uncover a mix of working features, broken features, and half-built features, categorize them immediately:
- Must Have: Core functionality currently working.
- Should Have: Functionality requested by users but missing/broken.
- Could Have: "Nice to have" features found in code but never used.
- Won't Have: Features found in old docs that are technically impossible or irrelevant.
Summary Checklist for Recovery
- Run the app: Document what happens.
- Read the DB: Understand the data structure.
- Read the Logs: Understand user behavior.
- Read the Tickets: Understand the history.
- Talk to the Users: Understand the "why."
Warning: The biggest risk in this process is institutionalizing a bug. Just because the code does something a certain way doesn't mean it's a requirement. Always verify "Implementation Reality" against "Business Intent" before signing off on a recovered requirement.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.