Update TigerFS skills to reflect better undo logic, reduce token cost#52
Merged
Conversation
…his cycle Skill recipes are updated to match current platform behavior. Some recipes that previously prescribed a path the platform now rejects have been rewritten; new recipes have been added for the agent-facing errors and the redirected entry points. Anti-pattern: Write/Edit (with their write-temp-then-rename semantics) is not a valid revert mechanism. The agent must use the .undo/ machinery -- savepoint-based or per-log-id. New "How agent writes appear in the log" workflow distinguishes atomic-rename writes (Claude's Write/Edit produce 2 log entries for a new file, 3 for an overwrite; create+rename share the temp's file_id, delete carries the original target's file_id) from direct writes (shell redirect produces a single create or edit entry). To revert a logical operation, group entries by adjacent timestamps and the <basename>.tmp.<pid>.<hash> -> <basename> filename pattern; apply each undo newest-first so each step lands on the state the next expects. The .log/.by/filename/<name>/ recipe is replaced with the two-step file_id pattern: Read <file>/.id via .history/, then read .log/.by/file_id/<uuid>/. The platform now rejects the old path because the log's filename column stores /-bearing full paths that can't be expressed as a single directory entry. The new pattern handles nested files and survives renames. The false ".history/.by/ root-only" claim is dropped from skills/tigerfs/files.md and docs/history.md (two locations). UUID browsing is addressable from .history/ at every level; the lookup is keyed only on file_id, so the surrounding directory does not scope the result. The .info/user wording clarifies that the file lives at the mount-root .info/, not the workspace-level .info/ (which holds backing-table metadata like count/schema). .tables/<workspace>/ is positioned as the data-first entry point. File-first workspaces reject data-first capability dirs (.by/, .filter/, .order/, .columns/, .first/, .last/, .sample/, .export/, .import/, .indexes/, .modify/, .delete/) with ErrInvalidPath and a hint pointing at the .tables/ route. The Operation Log section enumerates indexed columns (file_id, user_id, type) and notes that filename is explicitly blocked; other columns are technically path- addressable but unindexed. Pipeline-capability rule in SKILL.md split into three cases: hidden- but-accessible inside .log/.savepoint/; rejected at file-first workspace root or subdir; fully accessible on standalone data-first tables or under .tables/. Subdirectory comment in the SKILL.md directory tree clarified: .history/<file>/ remains path-accessible from subdirectories even though `ls` only lists real files.
Three low-risk redundancy removals; load-bearing rules unchanged. 1. Cut three redundant cross-links and an example: the "Each undo is itself logged with type=undo" sentence in the multi-entry log subsection (already covered by the "Undo is undoable" paragraph in Safe Editing); the illustrative example in "What changed in this file?" step 3; and two Quick Reference meta-rows that pointed at Common Workflows without conveying new information. 2. Collapse the "What you can build" section's five verbose "When asked to X: > Read recipes.md Recipe N" blocks into a single lookup table. The kanban core rule (directories = states; mv = transitions; no status frontmatter) is preserved inline in the table cell so it remains a load-bearing rule. 3. Drop the .tables/ bullet from "Which Mode?". The same information is already in the Directory Scanning Safety section (the three-way pipeline-capability rule, which is the more useful framing because it distinguishes the .log/.savepoint/ "hidden but accessible" case, the workspace "rejected" case, and the .tables/-or-standalone "fully accessible" case). Keeping "Which Mode?" focused on the two modes (file-first vs data-first) is cleaner. Net: 888 characters saved (15356 -> 14468, ~5.8%). Load-bearing content preserved: the Write/Edit anti-pattern row, the multi-entry log workflow with file_id grouping, the file_id two-step recipe, the three-way pipeline-capability rule in Directory Scanning Safety, and all Safe Editing intro bullets.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates the TigerFS skill to match current platform behavior (commit 1) and tightens SKILL.md to reduce token cost (commit 2). Two stacked commits, kept separate so review can focus on substance vs. compression.
Commit 1: skill content updates
Closes the skill audit. Same content as previously described:
Commit 2: SKILL.md tightening
Three low-risk redundancy removals; load-bearing rules unchanged:
Net: 888 chars saved (15356 → 14468, ~5.8%). All load-bearing rules preserved: Write/Edit anti-pattern, multi-entry log workflow, file_id two-step recipe, three-way pipeline-capability rule, Safe Editing intro.