Add troubleshooting documentation for common failures

[coisa]

Objective

Add troubleshooting documentation for common Fast Forward DevTools failures and recovery steps.

Current Limitation

Several common failure modes require project-specific knowledge: Composer auth, missing vendor files, branch protection, submodule pointer conflicts, no-TTY process execution, coverage thresholds, phpdoc template generation, and workflow preview cleanup.

Proposed Work

Create a troubleshooting guide that helps maintainers diagnose and resolve common local and CI failures.

Scope

• Composer install/authentication failures.
• Missing or stale vendor/ and lock-file mismatch issues.
• GitHub branch protection and bot commit behavior.
• .github/wiki submodule conflicts and resolution steps.
• No-TTY execution errors such as /dev/tty failures.
• Coverage threshold failures.
• PHPDoc/template generation issues.
• Reports/wiki preview cleanup issues.

Non-goals

• Replacing command reference pages.
• Documenting every third-party tool option.
• Changing code behavior.

Acceptance Criteria

Delivery Criteria

• A troubleshooting page exists under docs/ and is linked from the docs index or FAQ.
• The guide includes symptoms, likely causes, and recovery steps for each covered failure mode.
• The guide includes copy-pasteable commands where safe.
• The guide distinguishes local-only issues from CI/GitHub Actions issues.

Architectural / Isolation Criteria

• Documentation uses current repository command names and workflow names.
• The content avoids stale line-by-line workflow duplication.