docs: add GitHub Actions workflow root cause analysis and fix guide

Author: overwrite00

WORKFLOW_FIX_GUIDE.md

@@ -0,0 +1,126 @@
+# GitHub Actions Workflow Fix - Root Cause and Solution
+
+## ROOT CAUSE IDENTIFIED
+
+The workflow `project-automation.yml` **does NOT exist on the `main` branch** (the repository's default branch).
+
+### Why This Breaks Everything
+
+GitHub Actions has a specific behavior:
+- **Workflows are discovered and executed from the default branch (main) only**
+- When you create an issue or PR in the repository, GitHub searches the `main` branch for matching workflows
+- If the workflow file isn't on `main`, it cannot be triggered, regardless of whether it exists on other branches
+
+### Current State
+
+```
+Branch: develop     → project-automation.yml EXISTS ✓
+Branch: main        → project-automation.yml NOT FOUND ✗
+
+Comparison with working workflows:
+- release.yml       → EXISTS on both main and develop ✓
+- test_build.yml    → EXISTS on both main and develop ✓
+```
+
+## SOLUTION: Merge to Main Branch
+
+The workflow file must be accessible on the main branch. Since main is protected and requires PRs, follow these steps:
+
+### Step 1: Create a PR from develop to main
+
+```bash
+# Option A: Via gh CLI (recommended)
+gh pr create \
+  --title "ci: enable project automation workflow on main" \
+  --body "This PR brings the project-automation.yml workflow from develop to main, enabling it to trigger on issues and PRs." \
+  --base main \
+  --head develop
+
+# Option B: Via GitHub Web UI
+# 1. Go to: https://github.com/overwrite00/NullifyPDF
+# 2. Click "Contribute" → "Open pull request"
+# 3. Set base: main, compare: develop
+# 4. Title: "ci: enable project automation workflow on main"
+# 5. Submit
+```
+
+### Step 2: Wait for CI checks
+
+- The test_build.yml workflow will run on this PR (since it triggers on PRs to main)
+- Review any CI feedback
+
+### Step 3: Merge the PR
+
+- Once CI passes and you're ready, merge the PR to main
+- This will add project-automation.yml to the main branch
+
+### Step 4: Verify on Main
+
+After merge, verify the file exists on main:
+
+```bash
+git fetch origin main
+git cat-file -e origin/main:.github/workflows/project-automation.yml
+echo "If this shows no error, the workflow is now on main"
+```
+
+### Step 5: Test the Workflow
+
+Create a new test issue/PR from the main branch:
+
+```bash
+# Option A: Via GitHub Web UI - create issue on main branch context
+# Option B: Via gh CLI
+gh issue create \
+  --title "Test workflow automation" \
+  --body "Testing if workflow now triggers"
+```
+
+Then check GitHub Actions tab to see if project-automation runs.
+
+## EXPECTED BEHAVIOR AFTER FIX
+
+Once merged to main:
+
+1. ✓ Creating issues will trigger the workflow
+2. ✓ Creating/reopening PRs will trigger the workflow  
+3. ✓ Closing PRs will trigger the workflow
+4. ✓ Items will be auto-assigned to @overwrite00
+5. ✓ Items will be auto-added to the GitHub Project
+
+## TECHNICAL DETAILS
+
+### Why Develop-Only Doesn't Work
+
+In GitHub Actions, repository events like "issue created" or "pull request opened" are global events that aren't tied to a specific branch context. GitHub:
+
+1. Receives the event notification
+2. Searches the **default branch** for matching workflows
+3. Executes only workflows found on the default branch
+
+This is different from push/PR events which can be configured to filter by branch.
+
+### How to Verify Workflow is Accessible
+
+```bash
+# Check develop
+git cat-file -e origin/develop:.github/workflows/project-automation.yml
+# Should succeed
+
+# Check main (will fail until PR is merged)
+git cat-file -e origin/main:.github/workflows/project-automation.yml  
+# Currently fails - this is the problem
+```
+
+## SUMMARY
+
+| Component | Status | Issue |
+|-----------|--------|-------|
+| Workflow file syntax | ✓ Valid YAML | None |
+| Workflow file permissions | ✓ Correct | None |
+| Secret GH_PROJECT_TOKEN | ✓ Configured | None |
+| File on develop branch | ✓ Yes | N/A |
+| File on main branch | ✗ No | **ROOT CAUSE** |
+| GitHub Actions enabled | ✓ Yes | None |
+
+**Action Required**: Merge develop → main via PR to fix the issue.