Open legacy code with a read-only reconnaissance ticket

Is the handoff ready?

Use these checks before access expands or the first ticket begins.

Define one question

A legacy reconnaissance ticket works best when it names a single question the business can recognize. For example: why does an invoice export omit credit notes, or which service owns the retry that duplicates email notifications? A question tied to an observed symptom gives the investigator a trail to follow and gives the reviewer a way to judge whether the investigation is complete. Avoid assigning the entire repository as the subject. Broad discovery produces long notes with no decision and invites access that the team does not need. Start with one route, job, integration, or batch process and name the environments where it runs. The smaller boundary does not prevent the specialist from noticing adjacent problems; it gives those observations a place to be logged rather than folded into an invisible expansion. Write down what is already believed and label it as a hypothesis. The investigator can then confirm, contradict, or leave the belief unresolved. That structure is more useful than asking for a fresh explanation with no baseline, because it exposes where the team's mental model and the code disagree.

Keep the first pass read-only

Read-only access reduces both operational risk and review burden. The specialist can inspect source, commit history, issue links, sanitized logs, configuration names, and database schema without changing a record or deploying a branch. If the investigation needs a query, define it against a read replica or an approved export rather than production credentials with broad write scope. A read-only assignment also makes the evidence easier to trust. The reviewer does not have to wonder whether the system changed during the investigation or whether a test record was created by the investigator. The output is a description of the system as it existed at a recorded time, plus a list of what could not be observed.

Some legacy systems make even read access sensitive. Customer records, payment details, health information, and credentials may appear in logs or fixtures. Use masked extracts and record the access path instead of copying sensitive values into the deliverable. The reconnaissance note should say what was reviewed and what was deliberately excluded.

Map five artifacts

Ask for five compact artifacts: the entry point, the call path, the data touched, the configuration that changes behavior, and the tests or checks that currently cover the path. The entry point may be a route, queue consumer, cron job, webhook, or manual admin action. The call path should name the services and modules in order without reproducing the entire codebase. The data section should identify stores, tables, queues, buckets, and external APIs, including which fields are read and written. Configuration should list environment variables, feature flags, timeouts, and limits by name and purpose, never by secret value. The test section should distinguish automated coverage from manual checks and note the last known evidence date. Add a sixth artifact only if the system requires it, such as a deployment diagram or a list of scheduled jobs. Keeping the template small makes the result comparable across investigations and prevents the deliverable from becoming a second, stale documentation project.

Separate fact from assumption

A useful reconnaissance note marks each statement as observed in code, observed in a runtime record, reported by an owner, or inferred. Those labels matter because legacy behavior is often maintained by a workaround that no current developer designed. An inference can be a good lead, but it should not be presented with the same confidence as a log line or a test result. Record the commit, build, or environment version used for the review. Legacy systems often have long-lived branches, patched deployments, and configuration that differs from the repository default. Without a version marker, a later reader cannot tell whether the map describes the system in production or an older copy.

Keep an open-questions list with an owner for each item. Some questions need a current employee, some need a vendor, and some need a controlled experiment. The list is a sign of a careful investigation, not a failure to finish. It gives the client a concrete choice about what to resolve before authorizing a code change.

End with one bounded next step

The reconnaissance should conclude with a recommendation that fits the evidence. That may be a small fix, a test that reproduces the symptom, a monitoring gap to close, or a decision to leave the behavior alone. Avoid turning the first read-only ticket into a stealth rewrite proposal; a rewrite needs its own scope, risk review, and funding decision. Review the artifact with the technical owner and the person who operates the flow. Their corrections are part of the evidence and should be recorded with a date. If the map changes their understanding, capture the change rather than quietly updating the diagram and losing the reason for the next decision. Close by opening one follow-up ticket with explicit acceptance criteria and a named reviewer. The legacy map then becomes an input to controlled work instead of a document that is filed and forgotten.

Frequently asked questions

Sources

1. NIST Secure Software Development Framework

   Practices for understanding and managing software risk before change.

2. Microsoft Security Development Lifecycle

   Secure development practices referenced for legacy assessment.

3. Google Technical Writing courses

   Guidance for producing a concise, reviewable technical artifact.

4. GitHub Docs: About repositories

   Repository and history concepts used to scope read-only inspection.