I joined a company about two months ago where there is only one business analyst, and much of the project's business logic exists only in people's heads. At first, the tech lead explained the tickets and expected behavior verbally, which helped me make progress. However, the tech lead is leaving soon, the codebase and processes are already messy, and my manager still expects me to understand everything immediately.
Have you dealt with poorly documented projects where tickets are vague and you have no idea what is actually expected? How did you get up to speed, uncover the hidden business rules, and avoid making incorrect assumptions? I'm also worried about whether struggling in this situation could affect my probation period.
4 Answers
The code can tell you what the application currently does, but it cannot always tell you why the business wants that behavior. For those questions, talk to the analyst, users, support staff, or whoever handles the affected process. Compare their explanations with the actual implementation, because the system’s behavior may differ from everyone’s assumptions.
Characterization or integration tests are especially useful here. Capture the current behavior at important boundaries such as APIs, database operations, and service-to-service calls. Those tests become a living record of what the system does and help prevent accidental changes while you learn it.
AI tools can help summarize unfamiliar code, map modules, explain control flow, or suggest where a business rule might be implemented. They are useful for getting oriented, but they cannot reliably invent undocumented requirements. Treat their explanations as hypotheses and verify them against the running application, tests, source history, and knowledgeable people.
Also, don’t assume this situation is a personal failure. If tickets have no acceptance criteria and key knowledge leaves with one person, that is a process and management problem. Raise concrete blockers early, document the risks, and avoid taking responsibility for requirements nobody has provided.
Start by treating the existing system as something you need to reverse-engineer. Run it locally if possible, trace unfamiliar features with a debugger, inspect database changes and SQL queries, and follow the execution path from the API or UI into the business logic. Keep a running list of what you know, what you think is true, and what still needs confirmation.
For every unclear ticket, ask specific questions immediately instead of silently guessing. A useful format is: “I currently assume the behavior is X, but should it instead be Y?” That shows you’re moving forward while making the ambiguity visible to your manager and the business analyst.
This works much better than trying to understand the entire codebase at once. Start with the feature you actually need to change and expand outward only when necessary.
Use the departing tech lead’s remaining time for a structured handover. Ask for walkthroughs of the architecture, important services, data flows, deployment process, known failure points, and the business rules behind the highest-risk features. Record the sessions if company policy allows it, and turn the information into short, focused notes while it is still fresh.
Then document new discoveries as part of your normal work. Keep it practical: API contracts, setup instructions, operational troubleshooting, decisions, and examples of expected behavior. Documentation becomes much more useful when it is updated alongside code rather than treated as a separate project.
Make sure management knows that creating this documentation is work and will take time. It should be an explicit priority, not something you are expected to do invisibly on top of every deadline.
Exactly. Asking for clarification is not refusing to do the work; implementing an unverified guess and creating rework is usually the bigger problem.