From 4487a41c50ad410bc41cea3698b577f5c0b2a60d Mon Sep 17 00:00:00 2001 From: Jeffrey Urban Date: Thu, 11 Dec 2025 20:38:07 -0500 Subject: [PATCH 1/2] docs: Add workflow guidance for fixing issues vs working around them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive workflow document that enforces: - Treating all blocking issues as in-scope - Fixing root causes instead of adding workarounds - Rejecting conditional logic that bypasses problems This completes the guidance changes to prevent the pattern of hiding issues with test-skipping logic or deferring fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .claude/workflows/fixing-issues.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .claude/workflows/fixing-issues.md diff --git a/.claude/workflows/fixing-issues.md b/.claude/workflows/fixing-issues.md new file mode 100644 index 0000000..b6b0b0b --- /dev/null +++ b/.claude/workflows/fixing-issues.md @@ -0,0 +1,27 @@ +# Fixing Issues Workflow + +**Universal rule: Fix issues completely. Never work around them.** + +## When You Encounter Any Blocking Issue + +1. **Recognize it's blocking**: Test failures, validation errors, missing requirements +2. **Treat it as in-scope**: Regardless of when introduced or which repo +3. **Fix it completely**: Don't skip, bypass, or defer + +## Examples + +### ❌ WRONG: Working Around +- "This is a pre-existing issue, let's skip the test" +- "Let's fix the workflow in this PR and the formula in another PR" +- "Add conditional to skip this when X" + +### ✅ RIGHT: Fixing +- "The formula has invalid placeholders, let me populate it with real values" +- "The test is failing because the code is wrong, let me fix the code" +- "This requires fixing both the workflow AND the formula" + +## Before Proposing ANY Conditional Logic + +Ask: "Am I adding this condition to work around a problem I should fix?" + +If yes → Fix the problem instead From cc37ba0486fb18028f79a23fd8f71837400ff7b4 Mon Sep 17 00:00:00 2001 From: Jeffrey Urban Date: Thu, 11 Dec 2025 20:53:27 -0500 Subject: [PATCH 2/2] docs: Add critical guidance to prevent workarounds over fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two new critical sections to CLAUDE.md: 1. "Never Work Around Problems - Fix Them" - Mandatory questions before proposing solutions - Red flags indicating workarounds vs fixes - Required actions for blocking issues - Examples of wrong (workaround) vs right (fix) approaches 2. "Apologies and Promises Are Not Solutions" - Requirement for concrete documentation changes - Rejection of vague promises without actionable changes - Process for identifying and updating failed guidance These sections prevent the pattern of creating workarounds (like skipping tests) instead of fixing root causes (like template placeholders in formulas). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8a1ed78..0a71eb2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,6 +30,40 @@ This file is the **entry point** for Claude guidance. Detailed guidance is organ **State your answers to these questions and get user agreement BEFORE implementing.** +### Never Work Around Problems - Fix Them + +**MANDATORY: Before proposing any solution that involves skipping, bypassing, or working around an issue:** + +**STOP and ask these questions:** +1. "Am I fixing the root problem or hiding it?" +2. "Would this solution work if I removed the conditional/skip logic?" +3. "Am I adding complexity to avoid fixing something else?" + +**Red flags that indicate a workaround instead of a fix:** +- Adding conditional logic to skip tests/checks +- Calling issues "unrelated", "pre-existing", or "out of scope" +- Creating separate PRs to "deal with later" +- Weakening assertions or requirements +- Adding `|| true`, `--no-verify`, or similar bypass flags + +**Required action when you encounter blocking issues:** +- Treat ALL blocking issues as in-scope, regardless of when they were introduced +- Fix the root cause completely before proceeding +- If the fix seems large, ASK the user about approach - don't skip it + +**Example of WRONG approach:** +```yaml +# WRONG: Skipping tests to avoid fixing the real problem +- run: brew test-bot + if: steps.check.outputs.formula-changes == 'true' # ← Workaround! +``` + +**Example of CORRECT approach:** +```ruby +# RIGHT: Fix the actual problem +sha256 "411b24aea01846aa0c1f6fbb843c83503543d6fe7bec2898f736b613428f9257" # ← Real fix! +``` + ### Version Numbers **NEVER mention version numbers** (v0.x, v1.x, etc.) unless they have been explicitly agreed upon and documented in planning. Use: @@ -115,6 +149,24 @@ Before recommending user run ANY code that modifies their files or data: - If no supporting evidence is found, acknowledge the assumption and ask for clarification - Example: "I assumed X based on the comment at normalization_engine.py:117 which states '...'" +## Apologies and Promises Are Not Solutions + +**When you catch yourself:** +- Apologizing for a mistake +- Promising to "do better next time" +- Listing "prevention strategies" +- Saying you'll "watch for red flags" + +**STOP. That's not a solution.** + +**Instead, you MUST:** +1. Identify which guidance document failed to prevent this +2. Propose a specific, concrete change to that document +3. Show the exact text to add/modify +4. Explain how this change would have prevented the mistake + +**If you can't identify a documentation change, the reflection is incomplete.** + ## Navigation ### Scope-Specific Guidance