debugging

Establish the expected and observed behavior, affected operation, environment, revision, runtime and dependency versions, inputs, and relevant time interval. Read applicable project instructions, the affected callers and contracts, and relevant glossary entries or architecture decisions. An investigation request does not authorize a fix or deployment. Keep live investigation read-only until a specific correction is supported and authorized.

Select only the relevant reference. Each contains a read when condition.

• Incidents, read when diagnosing an outage, elevated errors, or production latency.
• CI failures, read when a pipeline fails, flakes, or differs from local execution.
• Database queries, read when SQL, locks, or connection exhaustion dominate the symptom.
• PHP-FPM and OPcache, read when FastCGI fails, workers saturate, or PHP serves stale code.
• Symfony, read when a request, profiler token, service binding, or environment loading points to Symfony.
• Runtime debugging, read when Node.js or Python state, timing, or stack inspection can distinguish causes.

Before changing behavior, run a bounded reproduction that asserts the user's exact symptom. Prefer an existing failing test, then an HTTP or CLI invocation, UI assertion, trace replay, or isolated harness. Preserve the invocation, relevant output, exit status, environment, and revision. Reading code to construct the reproduction is allowed. A setup failure or successful health check is not reproduction of the reported defect.

Minimize the failing scenario by removing one input, caller, configuration difference, or dependency at a time and rerunning it. Keep the actual call chain and concurrency required for failure. Pin clocks, seeds, data, and dependencies where relevant. For intermittent bugs, measure failures per attempts under bounded stress and preserve the schedule or seed. Do not prescribe arbitrary retry counts or treat one clean run as proof. For performance, capture a representative baseline with equivalent data, concurrency, and cache state before tuning.

If no reproduction is possible, record attempts and the missing access, artifact, or instrumentation. Continue independent read-only investigation. Ask only for the missing prerequisite. A human-only reproduction needs exact steps, timestamps, and redacted observations through an available user interaction channel, never a shell waiting for input. Do not claim regression proof from inspection alone.

Gather the smallest evidence set that separates causes. Correlate exact log lines, metrics with units and populations, trace spans with request identity, and relevant code, configuration, dependency, or deployment changes. Extract the supporting lines with timestamps and source locations before drawing conclusions from a long log. Follow surrounding context and rotated history when needed. A summary, truncated result, missing sample, or plausible narrative is not a measured cause. Redact secrets before displaying or saving commands and artifacts, including headers and payloads. Do not reconstruct masked values.

Locate the first broken contract in the actual path. Trace the bad value, exception, or wait backward through callers and component boundaries, comparing with a working equivalent. Distinguish the originating defect from downstream symptoms. A database wait does not justify an HTTP timeout increase, and a tool-runtime failure does not establish an application defect. Repair the responsible layer without changing unrelated access rules, supported events, or interfaces.

When the cause is uncertain, keep competing falsifiable hypotheses. For each, identify supporting evidence, counterevidence, a predicted observation, and a disconfirming result. Select the cheapest bounded experiment whose possible outcomes distinguish the leading explanations. Change one variable at a time. Prefer a breakpoint or targeted boundary probe over broad logging. Mark temporary instrumentation with a unique searchable identifier. Revisit the candidates after a failed experiment instead of stacking speculative fixes. Use a known-good comparison or authorized bisection when change history provides the distinguishing experiment.