docs: add 'never ignore lint warnings' working principle

[carlos-alm]

Summary

• Adds working principle Bump actions/checkout from 4 to 6 #2 to CLAUDE.md: "Never Ignore Lint Warnings"
• Requires always checking lint output for relevance, fixing warnings on touched code, and surfacing warnings on untouched code

Test plan

• Verify CLAUDE.md renders correctly
• Confirm new principle doesn't conflict with existing rules

[claude]

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

---

PR Review Complete

Reviewing PR #390: "docs: add 'never ignore lint warnings' working principle"

Todo List:

• Read and analyze the modified CLAUDE.md file
• Phase 1: Root cause analysis - understand the problem being solved
• Phase 2: Configuration change detection - check for high-risk changes
• Phase 3: Test integrity assessment
• Phase 4: Code quality review
• Provide final assessment with rating and recommendation

---

Root Cause Analysis

Problem Being Solved: This PR addresses a documentation gap around lint warning handling in Claude Code sessions. Based on the existing "Parallel Sessions" section (lines 154-169) which already mentions "Do not clean up lint/format issues in files you aren't working on", this principle codifies and expands the lint warning handling philosophy to ensure consistency across all Claude Code interactions.

Why This Approach: The approach is sound - it establishes clear, actionable guidelines for how Claude Code should handle lint warnings, balancing thoroughness (always check warnings) with session isolation (don't fix warnings in files you didn't touch). This aligns well with the existing parallel session safety rules.

Risk Assessment: LOW RISK - This is purely documentation that reinforces existing behavioral patterns. No code changes, no configuration relaxation.

Critical Concerns

None identified. This change:

• ✅ Does NOT relax any linting rules or configurations
• ✅ Does NOT lower test standards or disable checks
• ✅ Does NOT silence warnings - it explicitly requires checking them
• ✅ Reinforces existing good practices around session isolation

Code Quality Assessment

Strengths:

• Clear and actionable: The 4 bullet points provide specific guidance on when to fix vs. mention warnings
• Consistent with existing rules: Aligns perfectly with the "don't clean up other sessions' files" principle from the Parallel Sessions section (line 169)
• Practical workflow integration: References the specific command (npm run lint) and emphasizes reviewing output
• Balanced approach: Distinguishes between warnings on touched vs. untouched code

Minor observations:

• The principle integrates seamlessly with existing Working Principles structure
• Language is concise and unambiguous
• Cross-references existing rules appropriately

Test Plan Assessment:
The proposed test plan is appropriate for a documentation change:

• Verifying CLAUDE.md renders correctly
• Checking for conflicts with existing rules (none identified)

Final Assessment

## Root Cause Analysis
**Problem Being Solved**: Codifying lint warning handling practices to ensure consistency across Claude Code sessions and prevent silent dismissal of relevant warnings.
**Why This Approach**: Establishes clear guidelines that balance thoroughness with session isolation, reinforcing existing good practices.
**Risk Assessment**: LOW - Pure documentation enhancement with no configuration changes.

## Critical Concerns
None. This change strengthens code quality practices without relaxing any standards.

## Final Recommendation
- Rating: ⭐⭐⭐⭐☆ (4/5)
- Action: **APPROVE**
- Reasoning: Well-written documentation that addresses a real need for consistent lint warning handling. The principle is practical, aligns with existing session isolation rules, and reinforces good development practices. Only minor deduction because it's documentation rather than a feature enhancement.

Recommendation: This PR should be approved. It's a valuable addition to the Claude Code guidelines that will help maintain code quality while respecting parallel session boundaries.

---

[greptile-apps]

Greptile Summary

This PR adds Working Principle #2 — "Never Ignore Lint Warnings" to CLAUDE.md, instructing Claude Code sessions to always run npm run lint after edits, fix warnings on touched code, and surface (but not fix) warnings on untouched code. The addition is well-scoped and consistent with the existing linter setup (Biome, line 25) and the Parallel Sessions isolation rules (line 169).

• The new principle correctly references the existing npm run lint command already documented in the Commands section.
• The decision logic (fix if touched, report if not) aligns cleanly with the "one worktree per session" and staged-only-commit rules already enforced by the safety hooks.
• One minor clarity issue: the inline back-reference uses an informal paraphrase in quotes rather than the exact wording from the Parallel Sessions section — see the inline comment for a suggested fix to improve cross-reference consistency.

Confidence Score: 4/5

• Documentation-only change that is safe to merge; one minor wording clarification recommended for cross-reference consistency.
• The change is additive documentation with no code impact. The new principle is internally consistent with existing CLAUDE.md rules and the project's Biome linting setup. The only finding is a style-level cross-reference wording issue that improves clarity when fixed, but doesn't affect the correctness or safety of the principle itself.
• No files require special attention.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Edit code] --> B[Run npm run lint]
    B --> C{Any warnings?}
    C -- No --> D[Proceed / commit]
    C -- Yes --> E{Warning on code\nyou touched?}
    E -- Yes --> F[Fix the warning]
    F --> B
    E -- No --> G[Mention warning to user\ndo NOT fix it]
    G --> D

Loading

_{Last reviewed commit: 5d283a4}

[claude]

Claude Code is working…

I'll analyze this and get back to you.

View job run