diff --git a/context-audit/SKILL.md b/context-audit/SKILL.md new file mode 100644 index 0000000..6a48133 --- /dev/null +++ b/context-audit/SKILL.md @@ -0,0 +1,302 @@ +--- +name: context-audit +description: Audit missing or underloaded context before answering. Use when an agent may be missing relevant files, memory, links, screenshots, prior decisions, tool outputs, repository state, or external context. Forces inventory of loaded vs missing context, retrieval before conclusions, uncertainty marking, and a concise answer plan. +--- + +# Context Audit + +Use this skill when the agent is at risk of answering from vibes, stale memory, partial evidence, or a convenient but unverified interpretation. + +The central move: stop drafting the answer. Inventory what context is loaded, identify what is missing, retrieve the highest-value missing pieces, mark remaining uncertainty, then answer from contact with the actual materials. + +This is not a research rabbit hole. It is a short preflight check to prevent plausible nonsense. + +## When to use + +Use this skill when the user says things like: + +- "look this up" +- "what is this?" +- "do you remember?" +- "based on the screenshot" +- "read the thread" +- "check the repo" +- "what changed?" +- "why is this happening?" +- "before you answer, review context" +- "don't guess" +- "be more curious" + +Also use it proactively when: + +- the user provides a link, screenshot, voice note, file, or repo path +- the task depends on prior decisions or session history +- a name, book, project, person, street, repo, or acronym is unfamiliar +- the agent is tempted to complete from pattern rather than evidence +- multiple sources of truth may exist +- the user gives an approximate path, title, or reference +- the current answer would rely on memory but memory has not been checked +- a previous correction involved hallucination, stale context, or wrong source-of-truth selection + +## Core workflow + +### 1. Name the context risk + +Identify what kind of context may be missing: + +- File/repo context +- Memory context +- Link/thread context +- Screenshot/image context +- Audio/transcription context +- Prior-decision context +- External factual context +- Tool/output context +- Source-of-truth ambiguity + +This prevents the audit from becoming a vague pause before the same guessed answer. + +### 2. Inventory loaded context + +Briefly list what is already available in the current context. + +Examples: + +- user message text +- attached screenshot or file metadata +- attempted transcription +- current working directory +- git status summary +- known memory snippets +- visible prior turns +- loaded skill instructions +- fetched webpage contents +- inspected files + +Be concrete. "I have enough context" is not an inventory. + +### 3. Identify missing context + +List the missing items that could materially change the answer. + +Examples: + +- full thread behind a social post +- target file contents +- existing repo before creating a new directory +- recent memory note for a named person or project +- current branch and diff before editing +- webpage contents behind a link +- exact wording from an audio file if transcription is uncertain +- source-of-truth document for a policy, API, or design +- prior user correction on the same topic + +Do not retrieve everything. Retrieve what could change the answer. + +### 4. Retrieve before concluding + +Fetch or inspect the highest-value missing context before forming the answer. + +Common retrieval actions: + +- read the named file +- inspect the directory or repo status +- fetch the URL +- search memory for the person/project/reference +- read the full social thread, not just the linked post +- inspect the screenshot directly +- check recent commits or diffs +- verify an unfamiliar acronym, book, tool, or place +- load the relevant skill or procedure + +If retrieval is impossible, say so and mark the uncertainty. + +### 5. Mark uncertainty honestly + +Separate known facts from inferred possibilities. + +Use language like: + +```text +Known: +- ... + +Likely: +- ... + +Unresolved: +- ... +``` + +Do not launder uncertainty into confident prose. Fluency is not evidence. The model's ability to produce a plausible completion is exactly the problem this skill exists to interrupt. + +### 6. Make an answer plan + +Before answering, state the plan in one or two sentences: + +```text +I checked the repo and found the canonical file. I am going to answer from that file, note the one unresolved ambiguity, and avoid speculating about the external service because I did not fetch it. +``` + +The answer plan should be brief. It exists to discipline the response, not to become a second essay. + +### 7. Answer from contact + +Now answer the user's actual question. + +Keep the audit invisible or compact unless the user asked for a full diagnostic. The goal is better answers, not making the user watch the agent shuffle papers. + +## Output shape + +For a quick audit, use: + +```text +Context checked: +- ... + +Still uncertain: +- ... + +Answer: +... +``` + +For a fuller audit, use: + +```text +Context risk: + +Loaded: +- ... + +Missing / checked: +- ... + +Retrieved: +- ... + +Known: +- ... + +Unresolved: +- ... + +Answer plan: + + +Answer: +... +``` + +If the audit is internal and the final answer can be direct, skip the visible structure and just answer accurately. + +## Common failure modes + +- Treating an unfamiliar reference as a writing prompt. +- Reading the linked post but not the parent thread. +- Creating a new file or directory before finding the existing canonical repo. +- Answering from a screenshot without inspecting the actual image. +- Trusting an attempted transcription when a proper noun sounds wrong. +- Using stale memory when a current-state file exists. +- Fetching too broadly and burying the answer under research residue. +- Saying "I don't have enough context" when the context is retrievable. +- Saying "I checked" without naming what was checked. +- Letting a confident pattern match override a concrete artifact. + +## Practical heuristics + +### Unknown proper noun + +If a book, person, company, repo, street, tool, or acronym is unknown, retrieve or ask before interpreting it. + +Bad: + +```text +That sounds like a desert novel about isolation. +``` + +Good: + +```text +I don't know which Black Sun this is. I need to identify the reference before interpreting the recommendation. +``` + +### Approximate path or repo + +If the user says "some repository somewhere" or gives an approximate location, discovery is the task. + +Bad: + +```text +Create the directory and write the file. +``` + +Good: + +```text +Find the existing repo, inspect its remotes/status, then modify the canonical location. +``` + +### Screenshot or image + +Look at the actual thing before applying a symbolic frame. + +Bad: + +```text +This is probably about the project we discussed earlier. +``` + +Good: + +```text +The screenshot shows X. I can connect it to Y, but the visible artifact itself says Z. +``` + +### Link or social post + +Fetch the full context before replying. + +Bad: + +```text +React to the one visible post. +``` + +Good: + +```text +Read the parent thread, author, timestamp, and surrounding replies before deciding whether to answer. +``` + +### Memory-dependent answer + +If the answer depends on user preferences, prior corrections, or current state, search/load memory first. + +Bad: + +```text +You usually prefer... +``` + +Good: + +```text +Memory says the current source of truth is X; older notes may be stale. +``` + +## Relationship to other skills + +Use `context-audit` before work when the risk is missing evidence. + +Use `source-of-truth-finder` when the central problem is locating the canonical repo, file, document, or authority. + +Use `lagging-concepts` during iterative work when the evidence is available but stale framing is distorting the output. + +Use `failure-postmortem` after something has already gone wrong. + +## Practical principle + +Context is not decoration around the answer. Context is the substrate the answer is made from. + +The goal is not to be slower. The goal is to spend the cheap seconds that prevent expensive bullshit. diff --git a/failure-postmortem/SKILL.md b/failure-postmortem/SKILL.md new file mode 100644 index 0000000..eeef9ec --- /dev/null +++ b/failure-postmortem/SKILL.md @@ -0,0 +1,274 @@ +--- +name: failure-postmortem +description: Analyze a failure after a bad answer, failed tool call, broken command, correction, deploy issue, or workflow mistake. Use to separate proximate error from structural cause, identify prevention rules, and produce a concrete repair without apology theater. +--- + +# Failure Postmortem + +Use this after something went wrong and the next move needs to be learning, repair, or prevention rather than defensiveness. + +The central move: separate the visible failure from the mechanism that produced it. A failed command, bad answer, hallucinated detail, or broken deployment is usually the symptom. The useful question is what decision process made the failure likely. + +Do not perform an apology ritual. Diagnose the failure and change the operating rule. + +## When to use + +Use this skill when the user says things like: + +- "what happened?" +- "postmortem this" +- "why did that fail?" +- "handle the correction" +- "don't just apologize" +- "what rule prevents this?" +- "you did the wrong thing" +- "that command failed" +- "the deploy broke" +- "this is the same mistake again" + +Also use it proactively after: + +- a hallucinated fact or made-up reference +- a tool call that failed or timed out +- a command that produced unexpected output +- a wrong file/repository/path was modified +- a user correction reveals a bad assumption +- a test/build/deploy failure +- a privacy or publishing mistake +- repeated iteration shows the agent is optimizing the wrong thing +- a previous written rule failed to change behavior + +## Core workflow + +### 1. State the failure plainly + +Name what happened in one or two sentences. + +Bad: + +```text +Sorry, I can see how that might have been frustrating. +``` + +Good: + +```text +I created a new directory instead of finding the existing repository. That put the artifact in the wrong source of truth. +``` + +Keep the statement factual. Do not soften it into vibes. + +### 2. Separate proximate error from structural cause + +The proximate error is the immediate thing that went wrong. + +Examples: + +- wrong command +- missing credential +- stale path +- failed test +- unverified assumption +- bad tool selection +- timeout +- hallucinated detail + +The structural cause is the pattern that made the error likely. + +Examples: + +- acted before locating the canonical source +- optimized for speed over retrieval +- treated a fuzzy name as exact +- trusted a transcript artifact without plausibility checking +- preserved a stale concept from earlier work +- assumed a tool's existence from a capability list +- used a public-action workflow without privacy review +- relied on a written rule that had not become behavior + +If the postmortem stops at the proximate error, it will not prevent recurrence. + +### 3. Identify the decision point + +Find the moment where a different action would have prevented the failure. + +Useful prompts: + +- What did the agent know before acting? +- What did the agent assume without checking? +- What signal was ignored? +- What cheaper verification step was available? +- Was the action reversible? +- Was there a canonical source that should have been found first? +- Was the user asking for action, discovery, or judgment? + +The decision point should be specific enough that a future agent can recognize it. + +Bad: + +```text +Be more careful. +``` + +Good: + +```text +When a user names a repo or path approximately, search for existing repos and remotes before creating a new directory. +``` + +### 4. Name the prevention rule + +Convert the structural cause into a rule. + +Good rules are operational: + +- Before creating a file tree, check whether the target repository already exists. +- Unknown proper nouns are retrieval triggers, not autocomplete slots. +- If a command depends on local service state, verify the service and bound agent before assuming CLI syntax is enough. +- For public posts, fetch thread context before replying. +- If a skill appears in the available list but the Skill tool cannot load it, inspect the skill file and use the manual fallback. +- If a rule failed despite being written down, change routing, representation, or workflow rather than adding another scolding note. + +Bad rules are moralistic: + +- Be better. +- Don't mess up. +- Pay attention. +- Remember next time. + +A prevention rule should change behavior, not express regret. + +### 5. Repair or contain the damage + +Name what has already been repaired and what remains open. + +Examples: + +```text +Repaired: +- removed the mistakenly-created directory +- cloned the real repository +- copied the file into the canonical repo +- committed and pushed + +Open: +- update memory so future tasks use the canonical repo path +``` + +For failed commands: + +```text +Repaired: +- stopped the hung process via timeout +- confirmed no URL was produced + +Open: +- inspect local backend state before retrying +``` + +For bad answers: + +```text +Repaired: +- corrected the factual claim +- retrieved the source + +Open: +- encode the retrieval trigger if this is a recurring pattern +``` + +### 6. Decide whether memory or process needs updating + +Not every failure deserves a durable memory update. Use judgment. + +Update memory/process when: + +- the failure repeated +- the correction is broadly reusable +- a public or high-stakes workflow was affected +- the user explicitly asked for durable correction +- existing memory failed to fire +- a canonical path/source/credential/routing rule was discovered + +Do not update memory when: + +- the failure was one-off and obvious +- the lesson is already captured elsewhere +- the update would overfit to a transient incident +- storing it would clutter always-loaded context + +If updating memory, prefer a compact operational rule or canonical source pointer over a long shame chronicle. + +### 7. Resume from the corrected state + +A postmortem is not the end of the task unless the user asked only for diagnosis. + +After the failure is understood: + +- continue from the corrected source +- retry with the right preconditions +- produce the revised answer +- hand off the open issue +- stop if further action would be unsafe or speculative + +Do not linger in self-punishment. The point is prevention and repair. + +## Output shape + +Use a compact structure: + +```text +Failure: + + +Proximate error: +- ... + +Structural cause: +- ... + +Decision point: +- ... + +Prevention rule: +- ... + +Repair: +- done: ... +- open: ... + +Next action: +- ... +``` + +For lightweight failures, compress it: + +```text +The proximate error was X. The structural cause was Y. The rule is Z. I repaired A; B remains open. +``` + +## Common failure modes + +- Apologizing instead of diagnosing. +- Treating the tool error message as the whole cause. +- Blaming the user for ambiguous wording instead of handling ambiguity. +- Writing a broad rule that cannot be operationalized. +- Updating memory with incident clutter instead of a reusable trigger. +- Retrying the same command without changing preconditions. +- Treating a timeout as proof that nothing happened. +- Calling a partial repair complete. +- Turning the postmortem into a performance of humility. + +## Relationship to other skills + +Use `context-audit` before acting when the failure was missing context. + +Use `source-of-truth-finder` when the failure involved wrong paths, duplicate repos, stale files, or approximate names. + +Use `lagging-concepts` when the failure came from optimizing an old frame after the task moved. + +Use this skill after the failure has happened and the question is: what broke, why did it break, what rule prevents it, and what is now repaired? + +## Practical principle + +A useful postmortem is not an apology with bullet points. It is a patch to the agent's decision procedure. diff --git a/source-of-truth-finder/SKILL.md b/source-of-truth-finder/SKILL.md new file mode 100644 index 0000000..e6bca6a --- /dev/null +++ b/source-of-truth-finder/SKILL.md @@ -0,0 +1,275 @@ +--- +name: source-of-truth-finder +description: Find the canonical source before creating, editing, or answering when the user gives an approximate path, name, repo, person, project, document, issue, branch, or reference. Use to prevent duplicate artifacts, stale-file edits, wrong-repo work, and confident answers based on nearby-but-noncanonical context. +--- + +# Source of Truth Finder + +Use this when the user gives a fuzzy target and the next action depends on knowing which object is canonical. + +The central move: discovery before modification. Do not create a new file, edit the first plausible match, answer from memory, or run a command against an approximate target until you have identified the source of truth or explicitly marked that no canonical source was found. + +Approximate targets are common: + +- "the skills repo" +- "that note about Factory" +- "the branch from yesterday" +- "the PR where we fixed channels" +- "Nicki's Google thing" +- "the album prompt" +- "my local config" +- "the Tangled repo" +- "the agent with the Discord bug" + +A nearby object is not necessarily the right object. A path that looks intended may be a guess. A duplicate may be stale. A newly created artifact may be worse than no artifact, because it gives the system another false place to look next time. + +## When to use + +Use this skill when the user says things like: + +- "some repo somewhere" +- "I think it's in..." +- "go find..." +- "publish this to my skills repo" +- "update the note about..." +- "use the thing from last time" +- "fix the branch/PR/file" +- "where is the canonical..." +- "don't just make the folder" + +Also use it proactively when: + +- more than one plausible file or repo exists +- the target name is generic, overloaded, or approximate +- the requested path does not exist +- a memory says a canonical owner exists elsewhere +- the working directory is not obviously the target repo +- the task involves publishing, committing, deleting, or editing +- stale duplicates could cause future memory/retrieval failures +- the user is asking about a person/project that may have aliases + +## Core workflow + +### 1. Restate the target as a search problem + +Before acting, name what must be found. + +Bad: + +```text +Create ~/code/cameron-skills and write the skill. +``` + +Good: + +```text +Find Cameron's existing public skills repository, then add the new skill there if it exists. +``` + +Bad: + +```text +Edit the first note matching Factory. +``` + +Good: + +```text +Find the canonical competitive-intel note for Factory before editing. +``` + +This catches the crucial distinction between a requested artifact and the real object of the task. + +### 2. Generate candidate locations + +Search likely locations before modifying anything. + +For files and notes: + +- current working directory +- relevant project root +- user-provided path +- known vault or memory directories +- indexed note directories +- recent files +- filenames and contents matching key terms + +For repos: + +- existing local clones +- git remotes +- known hosting domains +- repo names in memory or docs +- sibling directories under common code roots +- remote URLs mentioned in config files + +For people or projects: + +- memory files +- recent event logs +- contact aliases +- prior conversations if available +- screenshots or linked artifacts +- public pages only when appropriate + +Do not stop at the first plausible result. Build a small candidate set. + +### 3. Score candidates for canonicality + +Prefer candidates with stronger ownership signals. + +Strong signals: + +- git remote matches the named host/org/user +- file lives in a documented canonical directory +- memory router or README points to it +- recent commits or edits match the task +- path/name exactly matches the requested domain +- existing related artifacts are already there +- user previously corrected toward this location +- metadata/frontmatter says it is canonical + +Weak signals: + +- directory name merely sounds right +- file contains a matching word once +- path was created during the current attempt +- search result is old and unmaintained +- duplicate exists without backlinks or recent use +- local scratch directory has no remote +- memory mentions it only as historical context + +If the best candidate is weak, say so before modifying. + +### 4. Check for stale duplicates + +Before editing, look for duplicates or mirrors that may disagree. + +Examples: + +- two repos with similar names +- local scratch clone and real remote clone +- system memory summary and detailed reference file +- vault note and memory file covering the same topic +- old branch and merged PR branch +- generated folder from a failed prior attempt + +When duplicates exist, identify the canonical owner and either: + +- edit only the canonical source +- remove or ignore the stale duplicate +- update stale pointers if the task requires it +- report the conflict if ownership is unclear + +Do not merge contradictory facts by vibe. Source ownership beats plausibility. + +### 5. Verify before modification + +Before writing, committing, deleting, or running a consequential command, verify: + +- path exists and is the intended location +- git branch and remote are correct +- working tree status is understood +- file being edited is canonical or intentionally new +- no sensitive/private content is being added to a public repo +- generated content has had user-specific details removed if publishing +- naming follows the target repo's convention + +For public artifacts, check for: + +- personal names that should be generalized +- secrets, tokens, local-only paths +- private relationship details +- proprietary company context +- agent-specific memory that should not be published + +### 6. Modify the canonical target only + +Once the source of truth is identified, act there. + +Safe modification pattern: + +1. read the existing target or neighboring examples +2. create or edit the intended file +3. inspect the result +4. check git status if in a repo +5. do not commit unless explicitly asked +6. report exact path and unresolved caveats + +If you created a wrong artifact during discovery, clean it up or clearly report it. Do not leave false sources of truth lying around. + +### 7. Report provenance + +A good final report says how canonicality was determined. + +Example: + +```text +Found the canonical skills repo at /home/cameron/code/cameron-skills because its remote is git@tangled.org:cameron.stream/skills and it already contains humorous-venting/SKILL.md. Added source-of-truth-finder/SKILL.md there. Did not commit. +``` + +This is more useful than: + +```text +Done. +``` + +"Done" is how ghosts enter the filesystem. + +## Output shape + +For small tasks, be concise: + +```text +Canonical target: +- +- Reason: + +Duplicates checked: +- : + +Action: +- + +Status: +- +``` + +For larger ambiguous tasks: + +```text +Search target: + + +Candidates: +- — +- — + +Canonical source: + + +Stale duplicates / conflicts: +- + +Safe next action: + +``` + +## Common failure modes + +- Creating the path the user named without checking whether it already exists elsewhere. +- Editing the first search hit because it looks plausible. +- Treating a scratch clone as the real repo. +- Trusting the current working directory by default. +- Updating a summary file when the canonical detailed file owns the domain. +- Copying private, user-specific notes into a public skill or repo. +- Leaving behind a mistakenly-created duplicate. +- Reporting success without saying which source was modified. +- Asking the user to locate the source when the environment contains enough evidence to search. +- Treating stale memory as current without checking the live owner. + +## Practical principle + +A source of truth is not the place where a fact can be found. It is the place responsible for that fact staying correct. + +Find responsibility before action. Otherwise the agent is not maintaining a system; it is manufacturing archaeology.