Troubleshooting
Isolate failures without chaotic reconfiguration.
Result
You reduce a failure to one reproducible layer and can show whether the repair restored the original acceptance criterion. Random reconfiguration is avoided.
| Layer | First evidence to collect |
|---|---|
| Installation | Version, supported system, diagnostic output |
| Authentication | Active account and sign-in result without secret values |
| Authorisation | Workspace identity, permission scope, denied action |
| Instructions | Effective root file, directory scope, conflicting rule |
| Tool or connector | Exact call, input shape, returned error, service identity |
| Data | Input path, version, format, required field, encoding |
| Output | Expected format, actual artifact, failed criterion, target-app view |
Actions
- Record the exact action, time, environment, input version, expected result, actual result, and first failed acceptance criterion.
- Preserve the complete error and relevant log excerpt after removing secret values; do not paraphrase away codes or paths.
- Reproduce the failure with the smallest safe input and no unrelated changes.
- Check one layer at a time, beginning with the input, project rules, active account, and permission boundary.
- Compare versions and configuration with the last accepted run and form one falsifiable cause hypothesis.
- Change one factor, repeat the minimal reproduction, and record whether the hypothesis was supported.
- Restore the original task and re-run its failed acceptance criterion before closing the issue.
Check
The record contains a minimal reproduction, failed layer, evidence for the cause, one bounded change, and a successful re-run of the original criterion on the intended data or artifact. A different command succeeding is not sufficient.
If it fails
Stop changing the environment and preserve versions, configuration, error text, and the minimal safe example. Restore the last accepted configuration when possible. Escalate with the failed layer, reproduction, expected and actual results, and checks already performed, but no credentials or private case data.
Next: Glossary.