What
/understand's Phase 7 step 4 (skills/understand/SKILL.md) cleans up its scratch directories with:
rm -rf $PROJECT_ROOT/.understand-anything/intermediate
rm -rf $PROJECT_ROOT/.understand-anything/tmp
On hosts with destructive-action safety policies (mine: 2-hour freshness window, three-search-angle verification, mandatory audit delegation before any rm/mv -f/unlink/etc.), this trips because the directories were created moments earlier by the same skill. My advisory hook fires; my blocking guard doesn't (low-risk classification); the command goes through but doctrine compliance failed.
No data is lost in practice — those dirs are skill-internal scratch already merged into knowledge-graph.json. The conflict is about the shape of the action, not the outcome.
Repro
- Install a PreToolUse hook on the Claude Code / Codex host that gates
rm -rf against a freshness window (e.g., refuse to delete files modified within the last 2h without an explicit auditor approval).
- Run
/understand . on any repo.
- Phase 7 step 4 fires
rm -rf .understand-anything/intermediate; the hook either blocks (forcing user to retry with override) or fires an advisory warning that the user is responsible for resolving.
Fix candidate
Replace the destructive rm -rf with a reversible mv to a timestamped trash dir, then opportunistically purge old trash on next run:
TRASH=$PROJECT_ROOT/.understand-anything/.trash-$(date +%s)
mv $PROJECT_ROOT/.understand-anything/intermediate $TRASH/ 2>/dev/null
mv $PROJECT_ROOT/.understand-anything/tmp $TRASH/ 2>/dev/null
# At Phase 0 of subsequent runs, purge .trash-* dirs older than 7 days:
find $PROJECT_ROOT/.understand-anything/ -maxdepth 1 -type d -name '.trash-*' -mtime +7 -exec rm -rf {} +Benefits:
mv is reversible (file metadata preserved), so destructive-action gates that require a freshness check let it through cleanly.- The 7-day delayed purge gives the user time to recover from a botched run.
- Same end-state for the user (clean
.understand-anything/ after a few runs) without the doctrine conflict.
Additional context
Happy to PR if the mv → .trash/ pattern looks right; would also be a tiny doc nit to add "destructive-action safety" to the failure modes the skill recipe acknowledges.
What
/understand's Phase 7 step 4 (skills/understand/SKILL.md) cleans up its scratch directories with:On hosts with destructive-action safety policies (mine: 2-hour freshness window, three-search-angle verification, mandatory audit delegation before any
rm/mv -f/unlink/etc.), this trips because the directories were created moments earlier by the same skill. My advisory hook fires; my blocking guard doesn't (low-risk classification); the command goes through but doctrine compliance failed.No data is lost in practice — those dirs are skill-internal scratch already merged into
knowledge-graph.json. The conflict is about the shape of the action, not the outcome.Repro
rm -rfagainst a freshness window (e.g., refuse to delete files modified within the last 2h without an explicit auditor approval)./understand .on any repo.rm -rf .understand-anything/intermediate; the hook either blocks (forcing user to retry with override) or fires an advisory warning that the user is responsible for resolving.Fix candidate
Replace the destructive
rm -rfwith a reversiblemvto a timestamped trash dir, then opportunistically purge old trash on next run:Benefits:
mvis reversible (file metadata preserved), so destructive-action gates that require a freshness check let it through cleanly..understand-anything/after a few runs) without the doctrine conflict.Additional context
.understandignore).Happy to PR if the
mv→.trash/pattern looks right; would also be a tiny doc nit to add "destructive-action safety" to the failure modes the skill recipe acknowledges.