How to use session artifacts
Find, save, review, and recover the files and evidence associated with a Buffaly session.
This page is for technical Buffaly users and operators who need to distinguish session artifacts from repo or wiki files, recover context after long-running work, inspect child-session outputs, or verify generated docs, task evidence, images, attachments, and message saves.
Quick answer
A session artifact is a file associated with a Buffaly session. Artifact management lists root session files and saved files under the session artifacts area. Root-level task-*.md files are durable task artifacts.
Show artifacts for the current session, including Plan.md, Scratch.md, task files, message artifacts, attachments, generated files, and images. For each item, show the session-relative path, why it matters, and whether it corresponds to a committed repo or wiki file.
Important distinction
Do not assume a session artifact is the final deliverable. When output belongs in a repo or wiki, verify the exact absolute or repo path.
Session-relative artifact path
Evidence under the session directory, useful for recovery and audit.
Repository or wiki path
A deliverable in the active repo or wiki that may need git status, review, and commit.
External output path
An absolute path, attachment, download, or integration destination outside the session artifact area.
What counts as an artifact
| Artifact kind | Typical path | Purpose |
|---|---|---|
| Session root files | Plan.md, Scratch.md, session.json | Route, working notes, and session metadata. |
| Task artifacts | task-*.md | Durable scope, acceptance criteria, decisions, validation, and final status. |
| Top-level artifacts | artifacts/<file> | Generated reports, summaries, drafts, diffs, or evidence files. |
| Images | artifacts/images/... | Screenshots, generated images, and visual evidence. |
| Attachments | artifacts/attachments/... | User-provided files or saved external inputs. |
| Shelf artifacts | artifacts/shelf/... | Parked work or reusable saved outputs. |
| Message artifacts | artifacts/messages/... | Saved message content or evidence extracted from conversation turns. |
Where artifacts are stored
Artifacts are under the session directory, but the exact sessions root is environment-specific. Ask Buffaly to report the session key and artifact paths instead of guessing.
List the current session key, Plan.md, Scratch.md, task files, and artifacts under images, attachments, shelf, and messages. Include session-relative paths and any absolute paths that are safe to show.
For a repository or wiki deliverable, provide the absolute destination path and ask Buffaly to verify that file exists there. Do not accept a session artifact alone as proof that the wiki or repo file was written.
Timeline relation
The timeline answers what happened. Artifacts answer what file or evidence was preserved.
Expected Buffaly behavior: identify the session and turn, inspect timeline or session history, list matching artifacts, read the artifact or target file, then distinguish supporting evidence from the final deliverable.
Plan, Scratch, and Tasks
Plan
Short route, status, next step, and blocker.
Scratch
Working observations, evidence, and investigation notes.
Task artifact
Durable scope, acceptance criteria, decisions, validation, and final status.
Update Plan with the next step only, append evidence to Scratch, and update the task artifact with acceptance criteria, changed files, validation result, and commit hash.
Child sessions and subagents
Child sessions have their own keys, timelines, and artifacts. A parent may summarize child output, but child artifacts may remain under the child session.
Ask for both parent and child artifacts, and require Buffaly to identify which file is the final deliverable versus supporting evidence.
Ask Buffaly to create or save artifacts
Save the current validation evidence as a session artifact, then report the artifact path and what source turn it came from.
Create a task artifact with scope, acceptance criteria, decisions, target paths, validation, blockers, and final status fields.
Write the article to the exact repository or wiki path, verify it exists there, and show scoped git status for the target path.
Summarize the relevant artifacts, identify which are evidence only, and name the final deliverable path if one exists.
Read and update safely
- Include the session key when you know it.
- Name the layer to update: task artifact, Scratch, Plan, session artifact, repo file, or wiki file.
- Avoid vague requests like “put it in the docs” unless you specify whether that means session artifact, active docs repo, or active wiki root.
Verify an artifact exists
- Ask for session key, artifact name, and artifact kind.
- Ask for last write time if available.
- Ask for the first heading or first lines to confirm content.
- List and read root-level task artifacts.
- For final articles, verify the exact absolute repo or wiki path exists, not only a session artifact.
- For repo or wiki outputs, ask for git status --short scoped to the target path.
Finding artifacts later
| What you remember | What to ask Buffaly |
|---|---|
| Session key | List artifacts in that session and summarize Plan, Scratch, and task files. |
| Topic | Search session history for the topic, then list matching artifacts. |
| Deliverable path | Find sessions mentioning the path and summarize related artifacts and task files. |
Common mistakes
Confusing artifacts with wiki files
Better prompt: “Verify the wiki file exists at the exact active wiki path, then show the session artifact that supports it.”
Writing relative to the wrong session
Better prompt: “Use this session key and report session-relative paths before saving.”
Leaving final output only in Scratch
Better prompt: “Move final scope, acceptance, validation, and status into a task artifact or repo file.”
Assuming parent has child artifacts
Better prompt: “List both parent and child artifacts, then identify the final deliverable.”
Troubleshooting
| Symptom | First checks | Good next prompt |
|---|---|---|
| Cannot find file | Session key, artifact paths, root task files, repo path, external path. | List session artifacts and verify whether the final deliverable exists elsewhere. |
| Article exists but not in wiki | Session artifact path versus active wiki path. | Copy or write the final article to the exact wiki path and verify scoped status. |
| Task restarted after compaction | Plan, Scratch, task artifacts, timeline, and latest artifact summary. | Recover from task artifacts and summarize the last completed step before acting. |
| Final answer mentioned artifact but it is not visible | Artifact name, kind, session key, last write time, first lines. | Locate the artifact by session key and prove it exists with path and content preview. |
| Child artifacts missing | Child session key, parent summary, child timeline, child artifact list. | Inspect child session artifacts directly and identify the final deliverable. |