observe-before-editing

parcadei's avatarfrom parcadei

Observe Before Editing

⭐2.2kstars🔀157forks📁View on GitHub🕐Updated Jan 10, 2026
[Debugging]

When & Why to Use This Skill

The 'Observe Before Editing' skill is a high-precision debugging methodology designed to improve software reliability by prioritizing empirical evidence over assumptions. It enforces a workflow where the agent must verify actual system outputs, log files, and directory states before attempting any code modifications. By confirming what the system actually produced versus what was expected, this skill minimizes incorrect fixes, reduces technical debt, and ensures a data-driven approach to root cause analysis.

Use Cases

  • Case 1: Verifying if a background process or hook successfully executed by checking for specific output files in hidden cache directories like .claude/cache/learnings/.
  • Case 2: Diagnosing 'silent failures' where a command appears to succeed but fails internally, by manually running the command to reveal hidden error messages or token limit issues.
  • Case 3: Resolving environment-specific bugs by inspecting both local project paths and global system paths to identify configuration mismatches.
  • Case 4: Investigating unexpected system behavior by analyzing the tail end of log files to capture real-time error traces before touching the source code.
nameobserve-before-editing
descriptionObserve Before Editing
user-invocablefalse

Observe Before Editing

Before editing code to fix a bug, confirm what the system actually produced.

Pattern

Outputs don't lie. Code might. Check outputs first.

DO

  1. Check if expected directories exist: ls -la .claude/cache/
  2. Check if expected files were created: ls -la .claude/cache/learnings/
  3. Check logs for errors: tail .claude/cache/*.log
  4. Run the failing command manually to see actual error
  5. Only then edit code

DON'T

  • Assume "hook didn't run" without checking outputs
  • Edit code based on what you think should happen
  • Confuse global vs project paths (check both: .claude/ and ~/.claude/)

Source Sessions

  • a541f08a: Token limit error was invisible until manual run revealed it
  • 6a9f2d7a: Looked in wrong cache path (~/.claude/ vs .claude/), assumed hook failure
  • a8bd5cea: Confirmed hook worked by finding output files in project cache
  • 1c21e6c8: Verified Artifact Index indexing by checking DB file exists