sphica 0.2.0 → 0.4.0

package/skills/trace/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: trace
-description: Stores the decisions made in the current session (decisions and rejected options, constraints, non-goals, dead ends, findings, deliberate debts, verifications, questions) and the current work status in the database. The conversation itself is recorded automatically, so pick only what keeps the next decision from going wrong. Use only when the user explicitly asks.
+description: Stores every decision made in the current session (decisions and rejected options, constraints, non-goals, dead ends, findings, deliberate debts, verifications, questions), the pull requests and issues they came up with, and the current work status in the database. Use only when the user explicitly asks.
 argument-hint: "[work theme]"
 disable-model-invocation: true
-allowed-tools: Read, Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" trace *)
+allowed-tools: Read, Edit(~/.sphica/drafts/**), Write(~/.sphica/drafts/**), Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" trace *)
 ---
 
 # trace — store decisions in a form you can look up next time
@@ -11,8 +11,8 @@ allowed-tools: Read, Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" trace *)
 Target: **$ARGUMENTS**
 
 Claude Code and Codex record conversations automatically (the owner's messages, the AI's last reply, edited files).
-**trace stores only the decisions picked from that conversation, and the current work status.** A "list of what was done" is already in git log,
-so do not write one.
+**trace stores the decisions picked from that conversation, and the current work status.** A "list of what was done" is already in git log,
+so do not write one. The whole session counts, including what was said before the conversation was compacted (context shows it).
 
 ## Failures this skill prevents
 
@@ -23,28 +23,31 @@ so do not write one.
 | Not writing what is unresolved | Work resumes as if it were understood, and stalls midway |
 | Writing assertions without evidence | They are read as facts and later overturned |
 | Deleting overturned decisions | Why it changed is lost, and the original option is proposed again |
-| Storing everything | Work logs push decisions out, and search becomes unreadable |
+| Storing work logs | Work logs push decisions out, and search becomes unreadable |
+| Dropping the pull request or issue a decision came with | The decision cannot be found from the number people remember |
 
 ## Flow
 
-`$M` is the CLI: `node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js"` in Claude Code, and `node "../../dist/cli.js"` from this Skill's directory
-in Codex (Sphica is not on Codex's PATH, and shell scripts do not run on Windows).
+`$M` is the CLI: `node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js"` in Claude Code. In Codex, it is `node "<absolute path of this Skill's directory>/../../dist/cli.js"`
+(Sphica is not on Codex's PATH, and shell scripts do not run on Windows). **Run every command from the repository root**; do not change
+into the Skill's directory.
 
 1. **Read the material**: `$M trace context`. It shows this session's conversation, touched files, items already recorded,
    and work in progress with its decision keys. If the conversation is not recorded yet, write from your own context.
    It stops when both Claude Code and Codex sessions are in the environment, so name your host
    with `--host claude-code` or `--host codex`
-2. **Write**: assemble the record JSON. The shape is below and in [example.json](example.json). **Do not create a file**
-   (pass it on stdin so it never stays in the repository)
-3. **Check**: put the JSON after `$M trace check - <<'TRACE'` and end with a `TRACE` line. It checks the shape and
-   rules without touching the database. If it is rejected, fix it before moving on
-4. **Store**: the same form with `$M trace save - <<'TRACE'`. The same key overwrites, and items you did not write stay (it appends).
-   Write `session` exactly as context showed it (it stops if it differs from the current session)
-5. **Report**: show the owner what was stored, in the same shape as Sphica's other output (`✦` for the title, Markdown tables, a final `╰─` line).
+2. **Write**: run `$M trace draft`. It prints an `id` and a `file` under `~/.sphica/drafts/`. Write the record JSON to that file with
+   your file-writing tool (not through the shell, and never inside the repository). The shape is below and in [example.json](example.json)
+3. **Check**: `$M trace check <id>`. It checks the shape and rules without touching the database. If it is rejected, fix the same file
+   and check again
+4. **Store**: `$M trace save <id>`. The same key overwrites, and items you did not write stay (it appends). Write `session` exactly as
+   context showed it (it stops if it differs from the current session). It removes the draft after storing; if it says the draft could
+   not be removed, the record is stored: do not save again
+5. **Report**: show the owner what was stored, in the same shape as Sphica's other output (Markdown tables, a final `╰─` line).
    Copy the closing line's counts exactly as save printed them
 
 ```
-✦ **sphica trace** · <work title>
+**sphica trace** · <work title>
 
 | kind | key | summary |
 |---|---|---|
@@ -70,13 +73,19 @@ an empty list clears them.
 
 ## What to store
 
-**Only what cannot be recovered from code, tests, AGENTS, or git, and whose absence would make the next decision go wrong.** Do not store
+**Every decision made in the session**, plus what cannot be recovered from code, tests, AGENTS, or git. Do not store
 a running commentary, verifications that simply passed, or state that matters only to this session. Answers the owner chose (shown as Q / A in context)
 are material for decisions themselves.
 
+When the conversation mentions a pull request or an issue, put it in the `refs` of the items it relates to (`pr:#<number>`, `issue:#<number>`).
+Search finds records by these numbers. If none is mentioned, add none.
+
+If context lists items already recorded in this session, write each again with the same key when it still holds or changed, set it to
+`retired` / `resolved` / `superseded` when it no longer does, and leave it out only when it stays as it is.
+
 | kind | What to write |
 |---|---|
-| `decision` | What was decided. `context` (why it was needed), `options` (`chosen: true` on the chosen one, `why` on rejected ones), `confirmation` (how to check it holds), `downsides` (disadvantages accepted knowingly) |
+| `decision` | What was decided. `context` (why it was needed), `options` (`chosen: true` on the chosen one, `why` on any rejected ones), `confirmation` (how to check it holds), `downsides` (disadvantages accepted knowingly) |
 | `constraint` | What must not change. If it applies to files, `files` with `role: "applies_to"`: the hook shows it before editing |
 | `non_goal` | What was decided not to do. Without it, whoever resumes widens the scope |
 | `dead_end` | A path tried that failed, and why it failed |
@@ -95,7 +104,8 @@ that a person must do with "Human:" (or the same marker in the conversation's la
 ## Rules check enforces
 
 - `key` is a meaningful word (lowercase letters and digits, `.` `_` `-`). `at` is ISO 8601 with an offset
-- A decision needs rejected options with their `why`. An accepted decision needs an option with `chosen: true` and a `confirmation`
+- A decision needs `options`, at least the one chosen (`chosen: true` when accepted). Rejected options are written only when some were
+  compared, each with its `why`. An accepted decision needs a `confirmation`
 - `confidence: "fact"` needs `refs` or an evidence file (`role: "evidence"`). If you cannot give one, use `inference`
 - **Do not delete overturned decisions.** Write the old decision's key in the new decision's `supersedes`. For a decision from another session,
   use the `<host>:<session>#<key>` form context shows. A decision marked `superseded` in this record