docs: add debugging patterns from eclair 404 fix learnings - #103

• Create ticket/issue

Follow the guide to enable codebase context checks.

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

• Create ticket/issue

Follow the guide to enable codebase context checks.

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status:
Missing dependency checks: The script invokes gh issue create without validating that the gh CLI is
installed/configured or providing actionable error messaging for common failure modes
(missing gh, not authenticated, wrong repo).

echo "Creating tech improvement task: $TITLE"
gh issue create \
    --title "$TITLE" \
    --body "$BODY" \
    --label "tech improvement"

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status:
Unvalidated user content: User-supplied parameters are embedded verbatim into the GitHub issue body, which may be
acceptable for documentation workflows but should be confirmed to not require
sanitization/guardrails (e.g., unintended mentions, links, or sensitive content
inclusion).

TITLE="$1"
REFERENCES="$2"
SUMMARY="$3"
FULL_DETAILS="$4"
ACCEPTANCE_CRITERIA="$5"

BODY="## References
${REFERENCES}

## Summary
${SUMMARY}

## Full Details
${FULL_DETAILS}

## Acceptance Criteria
${ACCEPTANCE_CRITERIA}"

Learn more about managing compliance generic rules or creating your own custom rules

Add a check to verify the gh CLI is installed before use, and provide a
user-friendly error message if it is not.

scripts/create-tech-improvement-task.sh [38-41]

+command -v gh >/dev/null 2>&1 || { echo >&2 "gh CLI not found; please install and authenticate it."; exit 1; }
 gh issue create \
     --title "$TITLE" \
     --body "$BODY" \
     --label "tech improvement"

• Apply / Chat

Improve argument validation by checking the exact number of arguments using $#
-ne 5 instead of checking if each of the first five arguments is an empty
string.

scripts/create-tech-improvement-task.sh [7-17]

-if [[ -z "$1" || -z "$2" || -z "$3" || -z "$4" || -z "$5" ]]; then
+if [[ $# -ne 5 ]]; then
     echo "Usage: ./scripts/create-tech-improvement-task.sh <title> <references> <summary> <full-details> <acceptance-criteria>" >&2
     echo "" >&2
-    echo "All 5 parameters are required:" >&2
+    echo "Exactly 5 parameters are required:" >&2
     echo "  <title>                - Task title" >&2
     echo "  <references>           - GitHub issues, PRs, or explanation of origin" >&2
     echo "  <summary>              - One paragraph: what and why" >&2
     echo "  <full-details>         - Implementation approach, affected files, context" >&2
     echo "  <acceptance-criteria>  - Checkboxes for completion criteria" >&2
     exit 1
 fi

• Apply / Chat

Improve script portability by changing the shebang from #!/bin/bash to
#!/usr/bin/env bash.

scripts/create-tech-improvement-task.sh [1]

-#!/bin/bash
+#!/usr/bin/env bash

• Apply / Chat