docs(claude): scope conditional instructions to avoid priority conflicts

[carlos-alm]

Summary

• Replace unconditional "must"/"always"/"every" language in CLAUDE.md with contextual guidance so agents can prioritize correctly instead of treating every instruction as equally mandatory
• Codegraph workflow steps changed from mandatory 4-step checklist to pick-what-fits menu with explicit skip clause for non-code files and trivial edits
• Worktree rule scoped from "every session" to "before making code changes" — read-only tasks skip it
• Sync-with-main scoped from "always" to "before new feature work" — continuing existing PR work doesn't force unnecessary syncs
• Bug-fix mandate scoped from "fix it unconditionally" to "flag it, fix if blocking" — prevents task derailment

Test plan

• Read updated CLAUDE.md and verify instructions are clear and unambiguous
• Confirm no behavioral rules were weakened — only made contextual

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Analysis

Reviewing PR #659: "docs(claude): scope conditional instructions to avoid priority conflicts"

Todo List

• Read and analyze the changed CLAUDE.md file
• Conduct Phase 1: Root Cause Analysis
• Conduct Phase 2: Configuration Change Detection
• Conduct Phase 3: Test Integrity
• Conduct Phase 4: Code Quality
• Conduct Phase 5: Backlog Compliance Assessment
• Provide final rating and recommendation

---

Root Cause Analysis

Problem Being Solved: The current CLAUDE.md contains overly rigid "must"/"always"/"every" language that creates priority conflicts when AI agents need to balance competing requirements. Agents may mechanically follow all instructions even when contextually inappropriate (e.g., running full codegraph workflow on documentation fixes, creating worktrees for read-only reviews).

Why This Approach: Converting absolute mandates to contextual guidance allows agents to exercise appropriate judgment. The changes preserve the intent while enabling smart prioritization:

• Codegraph workflow becomes optional for trivial/non-code edits
• Worktree isolation scoped to actual code changes
• Sync requirements differentiated between new feature work vs continuing PRs
• Bug handling becomes "flag and fix if blocking" vs "always derail task to fix"

Risk Assessment: ✅ LOW RISK - This is pure documentation refinement that improves agent behavior without weakening any actual behavioral requirements.

Configuration Change Detection

✅ NO HIGH-RISK CHANGES DETECTED - No linting rules, test configurations, build settings, or TypeScript strict flags touched. This is purely documentation improvement.

Test Integrity

✅ NO TEST-RELATED RED FLAGS - No test files modified, assertions weakened, timeouts increased, or coverage thresholds lowered.

Code Quality Assessment

✅ EXCELLENT DOCUMENTATION QUALITY - Clear language improvements, maintains all behavioral intent, adds helpful contextual guidance, eliminates poor agent prioritization triggers.

Backlog Compliance

• Zero-dep: ✓ — No new runtime dependencies added
• Foundation-aligned: ✓ — Fully compliant with all FOUNDATION.md principles. Actually improves alignment by preventing agents from mechanically executing unnecessary workflows that waste compute (P4: zero-cost core)
• Problem-fit: 5/5 — Directly addresses core problem of AI agents wasting tokens on inappropriate workflows. This change prevents "re-orienting" waste by giving agents contextual guidance to skip irrelevant steps
• Breaking: No — Purely additive documentation improvements, no API/CLI contract changes
• Tier: Tier 1 (zero-dep ✓ + foundation-aligned ✓)

Critical Concerns

NONE - This is exemplary documentation improvement work.

Final Recommendation

Root Cause Analysis

Problem Being Solved: CLAUDE.md contained rigid mandatory language causing agents to mechanically execute inappropriate workflows (e.g., full codegraph analysis on doc-only changes, worktrees for read-only reviews)
Why This Approach: Converts absolute mandates to contextual guidance, enabling smart prioritization while preserving all behavioral intent
Risk Assessment: Extremely low risk - pure documentation refinement with clear improvement to agent decision-making

Backlog Compliance

• Zero-dep: ✓ — no new deps
• Foundation-aligned: ✓ — improves P4 compliance (zero-cost core) by preventing unnecessary workflow execution
• Problem-fit: 5 — directly reduces AI token waste from inappropriate re-orientation
• Breaking: No
• Tier: 1

Critical Concerns

None.

Final Recommendation

• Rating: ⭐⭐⭐⭐⭐ (5/5)
• Action: APPROVE
• Reasoning: Exceptional documentation improvement that directly addresses core AI agent efficiency problems. Zero risk, high value, perfect execution.

---

[greptile-apps]

Greptile Summary

This PR refines CLAUDE.md by replacing four unconditional imperatives with context-aware guidance, reducing priority-conflict noise for agents without weakening any safety-critical rule.

Changes:

• Codegraph pre-modification commands — converted from a mandatory numbered checklist to a "pick what fits" bullet list with an explicit skip clause scoped to those four commands only. The post-modification codegraph diff-impact --staged -T check remains unconditional in its own sub-section, and the previous review's concern about the referent of "Skip these" was addressed by changing it to "Skip the above commands" (aa6f647).
• Worktree rule — scoped from "every session" to "before making code changes"; read-only tasks (reviews, analysis, questions) are explicitly exempted.
• Sync-with-main rule — narrowed from "always before feature work" to "before new feature work"; continuing existing PR work requires sync "only if needed" (see inline comment for a minor vagueness here).
• Bug-fix mandate — changed from an unconditional "fix the bug" to "flag it to the user and fix if blocking," preserving the "don't work around it or ignore it" guardrail.

Confidence Score: 5/5

Safe to merge — documentation-only change with no runtime impact, and no P0/P1 issues found.

All findings are P2. The only substantive concern (ambiguous "Skip these" referent) was resolved in aa6f647 per the prior review thread. The remaining vagueness around "sync only if needed" is minor and doesn't affect correctness.

No files require special attention.

Important Files Changed

Filename	Overview
CLAUDE.md	Documentation-only PR scoping four previously unconditional rules (codegraph workflow, worktree, sync, bug-fix mandate) to their appropriate contexts; "Skip the above commands" referent was tightened in aa6f647 per prior review; one mild vagueness remains around "sync only if needed"

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([Agent starts task]) --> IsCodeChange{Making code\nchanges?}
    IsCodeChange -- No --> ReadOnly[Read-only task\nSkip worktree\nSkip pre-commands]
    IsCodeChange -- Yes --> Worktree[Run /worktree]
    Worktree --> IsNewFeature{New feature\nor continuing PR?}
    IsNewFeature -- New feature --> SyncMain[Sync with origin/main]
    IsNewFeature -- Continuing PR --> SyncIfNeeded[Sync only if needed]
    SyncMain --> PreCommands
    SyncIfNeeded --> PreCommands
    PreCommands{Non-code file,\ntrivial edit, or\nsufficient context?}
    PreCommands -- Yes --> SkipAbove[Skip the four\npre-modification commands]
    PreCommands -- No --> RunCommands[Pick relevant codegraph\ncommands: where / audit /\ncontext / fn-impact]
    RunCommands --> Modify[Modify code]
    SkipAbove --> Modify
    Modify --> DiffImpact[codegraph diff-impact\n--staged -T\nunconditional]
    DiffImpact --> Commit[Commit staged files]

Loading

_{Reviews (2): Last reviewed commit: "fix(docs): disambiguate skip-clause refe..." | Re-trigger Greptile}

[greptile-apps]

Ambiguous referent for "these"

The word "these" at line 20 immediately follows the four "Before modifying code" bullets, but a reader (or an agent) parsing the document linearly could interpret it as applying to all commands in the Codegraph Workflow section — including codegraph diff-impact --staged -T in the "After modifying code" subsection. That post-commit check is the most important safety step and should stay unconditional.

Consider making the scope explicit:

Suggested change

	Skip these for non-code files, trivial edits, or when you already have sufficient context.
	Skip the above commands for non-code files, trivial edits, or when you already have sufficient context.

[carlos-alm]

Fixed — changed "Skip these" to "Skip the above commands" in aa6f647, making it explicit that the skip clause applies only to the four pre-modification bullets and not to the unconditional codegraph diff-impact --staged -T post-commit check.

[carlos-alm]

@greptileai