docs: add Trellis planning and project specs
This commit is contained in:
81
.claude/skills/trellis-session-insight/SKILL.md
Normal file
81
.claude/skills/trellis-session-insight/SKILL.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: trellis-session-insight
|
||||
description: "Reach into past AI conversation history through the `trellis mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize."
|
||||
---
|
||||
|
||||
# Trellis Session Insight
|
||||
|
||||
This skill teaches an AI **how to call `trellis mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
|
||||
|
||||
It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
|
||||
|
||||
## What `trellis mem` is
|
||||
|
||||
A local CLI that indexes the user's past Claude Code, Codex, and Pi Agent conversation logs (the JSONL files each platform stores under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/`) and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
|
||||
|
||||
Nothing in `mem` is uploaded. All reads are local.
|
||||
|
||||
## When to reach for it
|
||||
|
||||
The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
|
||||
|
||||
- **Brainstorm rerun risk.** Starting a new task that touches an area the user has been in before, and you want to check whether a decision was already made — before re-asking the user.
|
||||
- **Familiar-bug debugging.** The current bug pattern feels like one the user reported / fixed before. Pulling the relevant past session can save a full debugging loop.
|
||||
- **Cross-session continuation.** The user resumes work after a gap and says "where were we" / "继续上次的" without being specific.
|
||||
- **Decision retrieval.** The user references "the decision we made about X" but the decision lives in an old brainstorm, not in any `prd.md` / `spec/`.
|
||||
- **Finish-work retrospective.** When the user explicitly asks for a wrap-up of what was decided / what hurt / what surprised them in this task — not as a forced step on every finish-work.
|
||||
- **Pattern-spotting across past work.** The user asks "do I keep making the same mistake on X" / "我每次都踩这个坑吗" — search across sessions answers that.
|
||||
|
||||
If none of these apply, don't call `mem`. It is a tool, not a ceremony.
|
||||
|
||||
## When NOT to reach for it
|
||||
|
||||
- The relevant context is already in the current turn, `prd.md`, `design.md`, recent `git log`, or the open files. `mem` is for stuff that has fallen out of immediate reach.
|
||||
- The user is asking about a fact in the code, not a fact from a past conversation. `git log -p` / `grep` / reading the file directly is faster and more authoritative.
|
||||
- You are in a sub-agent (`trellis-implement` / `trellis-check`) whose dispatch prompt already includes the curated `implement.jsonl` / `check.jsonl` context. Adding `mem` on top usually just clutters.
|
||||
- The user has explicitly said "don't dig through history, just answer what I asked".
|
||||
|
||||
## What to do with what `mem` returns
|
||||
|
||||
Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
|
||||
|
||||
- **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
|
||||
- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
|
||||
- **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
|
||||
- **Update `.trellis/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `trellis-update-spec` skill for that — `session-insight` ends at the discovery.
|
||||
- **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
|
||||
|
||||
Trellis does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
|
||||
|
||||
## How to call it
|
||||
|
||||
Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
|
||||
|
||||
```bash
|
||||
# Find sessions whose contents mention a keyword (project-scope is default;
|
||||
# add --global to search every project on this machine).
|
||||
trellis mem search "<keyword>"
|
||||
|
||||
# Dump dialogue from one session, optionally filtered by phase or keyword.
|
||||
trellis mem extract <session-id> --phase brainstorm
|
||||
trellis mem extract <session-id> --grep "<keyword>"
|
||||
|
||||
# Drill into a session: top-N hit turns + surrounding context.
|
||||
trellis mem context <session-id> --turns 3 --around 2
|
||||
|
||||
# When you do not know the session id yet, start with list + filter.
|
||||
trellis mem list --cwd <project-path>
|
||||
trellis mem projects # → list active project cwds, then narrow
|
||||
```
|
||||
|
||||
Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
|
||||
|
||||
## Triggering patterns
|
||||
|
||||
`references/triggering-patterns.md` lists more verbatim user phrasings (English + Chinese) that should make you think "reach for `mem`" — keep that handy when training instinct.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- `mem` does not edit code or update files. Any write-back is your decision in the moment.
|
||||
- `mem` is read-only on the platform JSONL stores. It does not push or sync to remote.
|
||||
- This skill does not replace `trellis-update-spec` (which is the right tool for promoting a finding into project-wide guidance) or the platform-native task / spec workflow.
|
||||
@@ -0,0 +1,65 @@
|
||||
# `trellis mem` CLI Reference
|
||||
|
||||
Full flag reference for the five subcommands. Pin this as the authoritative source — `trellis mem help` prints the same content at runtime, so anything here that drifts is a bug.
|
||||
|
||||
## Subcommands
|
||||
|
||||
| Command | Purpose |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `list` | List sessions. Default subcommand when none is given. |
|
||||
| `search <keyword>` | Find sessions whose contents match a keyword. |
|
||||
| `context <session-id>` | Drill into one session: top-N hit turns + surrounding context. Pair with `--grep` for keyword anchoring. |
|
||||
| `extract <session-id>` | Dump cleaned dialogue. Combine with `--phase` / `--grep` to slice. |
|
||||
| `projects` | List active project `cwd` values with session counts. Use this to discover which `--cwd` to pass to other subcommands. |
|
||||
|
||||
## Flags (apply where meaningful)
|
||||
|
||||
| Flag | Subcommands | Meaning |
|
||||
| --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--platform claude\|codex\|opencode\|pi\|all` | all | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below. |
|
||||
| `--since YYYY-MM-DD` | list / search | Inclusive lower date bound. |
|
||||
| `--until YYYY-MM-DD` | list / search | Inclusive upper date bound. |
|
||||
| `--global` | list / search | Include sessions from every project on this machine. Default is the current project `cwd`. |
|
||||
| `--cwd <path>` | list / search | Force a specific project cwd instead of inferring from where you are. |
|
||||
| `--limit N` | list / search | Cap output rows. Default `50`. |
|
||||
| `--grep KW` | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated. |
|
||||
| `--phase brainstorm\|implement\|all` | extract | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
|
||||
| `--turns N` | context | Number of hit turns to return. Default `3`. |
|
||||
| `--around N` | context | Surrounding turns to include per hit. Default `1`. |
|
||||
| `--max-chars N` | context | Total character budget. Default `6000` (~1500 tokens). |
|
||||
| `--include-children` | search / context | Merge OpenCode sub-agent sessions into their parent session. |
|
||||
| `--json` | all | Emit machine-parseable JSON instead of human-readable output. |
|
||||
|
||||
## Common one-liners
|
||||
|
||||
```bash
|
||||
# What past sessions discussed "deadlock" anywhere on this machine?
|
||||
trellis mem search "deadlock" --global --limit 20
|
||||
|
||||
# Inside a specific session, surface the top 5 turns that mention "lock contention"
|
||||
# plus 2 turns of surrounding context.
|
||||
trellis mem context 5842592d --grep "lock contention" --turns 5 --around 2
|
||||
|
||||
# Recover the brainstorm window for a session — useful when continuing a task
|
||||
# the user started a week ago.
|
||||
trellis mem extract 5842592d --phase brainstorm
|
||||
|
||||
# List every project this machine has Trellis sessions for, with counts.
|
||||
trellis mem projects
|
||||
```
|
||||
|
||||
## Output shapes
|
||||
|
||||
- **Default human output** (no `--json`): wrapped to a terminal, with session ids highlighted and turn markers visible. Suitable to read inline but messy to paste into a markdown file.
|
||||
- **`--json`**: stable schema, safe to parse and process. When piping `mem` output into a follow-up step (e.g. summarizing for a Lessons section), prefer `--json`.
|
||||
|
||||
## Caveats
|
||||
|
||||
- **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
|
||||
- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
|
||||
- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex / Pi session storage, `mem` cannot recover what is no longer on disk.
|
||||
- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
|
||||
|
||||
## When you need more than this reference
|
||||
|
||||
Run `trellis mem help` in the user's shell. The runtime help is authoritative and will be ahead of this reference during fast-moving beta releases.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Triggering Patterns
|
||||
|
||||
Verbatim user phrasings that should make an AI reach for `trellis mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
|
||||
|
||||
Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
|
||||
|
||||
## Past-solution recall
|
||||
|
||||
The user is asking "how did we (or I) solve this before". Past dialogue holds the answer; the codebase shows the result but not the reasoning.
|
||||
|
||||
- "How did we solve this last time?"
|
||||
- "What did we end up doing about X?"
|
||||
- "We dealt with this once already, didn't we?"
|
||||
- "上次怎么解的?"
|
||||
- "之前是怎么搞定 X 的?"
|
||||
- "我记得以前修过类似的"
|
||||
|
||||
Reach: `trellis mem search "<symptom keyword>" --global --limit 10`, then `context` into the hit that looks closest.
|
||||
|
||||
## Decision retrieval
|
||||
|
||||
The user is referencing a decision that lives in old dialogue, not in any committed file. Look in brainstorm windows.
|
||||
|
||||
- "What was the decision on X?"
|
||||
- "Did we decide to use Postgres or SQLite?"
|
||||
- "The rationale for choosing X over Y was…?"
|
||||
- "我们当时为啥选了 X 而不是 Y?"
|
||||
- "关于 X 我们之前是怎么定的?"
|
||||
- "之前讨论过 X 的方案吗?"
|
||||
|
||||
Reach: `trellis mem search "<decision keyword>"` to find the session, then `extract <id> --phase brainstorm` to recover the discussion.
|
||||
|
||||
## Cross-session continuation
|
||||
|
||||
The user resumed work after a gap and the context is implicit.
|
||||
|
||||
- "Where were we?"
|
||||
- "Continue from last time."
|
||||
- "Pick up where we left off."
|
||||
- "继续上次的"
|
||||
- "我们上次做到哪了"
|
||||
- "接着昨天那个任务"
|
||||
|
||||
Reach: `trellis mem list --task <current-task-dir>` to find the most recent sessions tied to the active task, then `extract` the last one.
|
||||
|
||||
## Familiar-bug debugging
|
||||
|
||||
The current bug feels like one already seen. Past sessions probably hold the resolution path.
|
||||
|
||||
- "I feel like I've hit this before."
|
||||
- "Doesn't this look like that bug from last month?"
|
||||
- "Same kind of timeout I had in X."
|
||||
- "这个错好像之前见过"
|
||||
- "这个 bug 是不是上次那个?"
|
||||
- "怎么又是这个 error?"
|
||||
|
||||
Reach: `trellis mem search "<error message fragment>" --global`. Anchor on a short, distinctive token from the actual error string.
|
||||
|
||||
## Self-pattern spotting
|
||||
|
||||
The user is asking whether they keep repeating the same kind of mistake or decision.
|
||||
|
||||
- "Do I always make this mistake?"
|
||||
- "How often have I run into X?"
|
||||
- "Is this a recurring thing for me?"
|
||||
- "我每次都踩这个坑吗?"
|
||||
- "我老犯这个错?"
|
||||
- "这类问题之前出现过几次?"
|
||||
|
||||
Reach: `trellis mem search "<topic>" --global --limit 50` and scan the dates / projects in the listing. Optionally `extract` two or three for comparison.
|
||||
|
||||
## Finish-work retrospective (on demand)
|
||||
|
||||
The user explicitly wants to look back at this task — not as a forced step, only when they ask.
|
||||
|
||||
- "Summarize what we did in this task."
|
||||
- "What were the key decisions / surprises?"
|
||||
- "Write up the lessons from this round."
|
||||
- "总结一下这次的经验"
|
||||
- "记一下这次踩的坑"
|
||||
- "复盘下这个任务"
|
||||
|
||||
Reach: identify the current task's session id (from `.trellis/.runtime/sessions/*.json` or `mem list --task <task-dir>`), then `extract <id> --phase brainstorm` and `--phase implement`. Present a summary — surface concrete file:line citations where possible. Whether to also write the summary somewhere (PRD, spec, notes file) is the user's call; offer, don't auto-write.
|
||||
|
||||
## Anti-patterns: do NOT reach for `mem` here
|
||||
|
||||
- "What does this function do?" → read the file.
|
||||
- "Why is this test failing?" → read the test output and the file.
|
||||
- "What's the right pattern for X in our codebase?" → grep / read spec files.
|
||||
- "What's the latest npm version of Y?" → call `npm view`.
|
||||
- "Fix this bug." → debug. Reach for `mem` only if you suspect prior context exists; otherwise it is noise.
|
||||
|
||||
The bar stays: would a senior teammate ask "didn't we already talk about this?" before answering? If yes, reach for `mem`. If no, don't.
|
||||
Reference in New Issue
Block a user