specs/debug-logging.md

@@ -0,0 +1,47 @@
+# Debug Logging Specification
+
+## Goal
+Implement comprehensive HTTP request/response logging for debugging API interactions between banks2ff and external services (GoCardless and Firefly III).
+
+## Requirements
+
+### Output Format
+Each HTTP request-response cycle generates a single text file with the following structure:
+
+1. **Curl Command** (at the top in comments)
+   - Full `curl -v` command that reproduces the exact request
+   - Includes all headers, authentication tokens, and request body
+   - Properly escaped for shell execution
+
+2. **Complete Request Data**
+   - HTTP method and URL
+   - All request headers (including Host header)
+   - Full request body (if present)
+
+3. **Complete Response Data**
+   - HTTP status code and reason
+   - All response headers
+   - Full response body
+
+### File Organization
+- Files stored in `./debug_logs/{service_name}/` directories
+- Timestamped filenames: `YYYYMMDD_HHMMSS_REQUESTID.txt`
+- One file per HTTP request-response cycle
+- Service-specific subdirectories (gocardless/, firefly/)
+
+### Data Visibility
+- **No filtering or masking** of any data
+- Complete visibility of all HTTP traffic including:
+  - Authentication tokens and credentials
+  - Financial transaction data
+  - Personal account information
+  - API keys and secrets
+
+### Activation
+- Enabled via `--debug` command-line flag
+- Files only created when debug mode is active
+- No impact on normal operation when debug mode is disabled
+
+### Use Case
+Human debugging of API integration issues where complete visibility of all HTTP traffic is required to diagnose problems with external service interactions.</content>
+<parameter name="filePath">specs/debug-logging.md