@codacy/verity-cli 0.32.5-experimental.4d91ca0 → 0.32.6-experimental.833e71a

package/data/skills/verity-reflect/SKILL.md

@@ -1,20 +1,22 @@
 ---
 description: >-
   Capture a durable learning at the end of a task: draft a concrete, cited observation from
-  what actually happened, then confirm it with the user or record it directly. Use at natural
+  what actually happened and record it straight into the project knowledge base. Use at natural
   task-completion moments, or when the user asks to record a lesson.
 ---
 # /verity-reflect — Capture learnings after a task
 
-At a natural task-completion moment, **the agent reflects first** — draft a
-concrete, cited observation from what actually happened — then either confirm it
-with the user (interactive) or record it directly (autonomous). This is the
-"reflection flip": Verity stops asking the user to do the reflecting and instead
-does the work, with the human as editor rather than author.
+At a natural task-completion moment, **the agent reflects and records** — draft a
+concrete, cited observation from what actually happened, write it to the project
+knowledge base, and say what you wrote. No question, no waiting.
 
-## The flip — draft first, then confirm or auto-record
+This is the second half of the "reflection flip". Verity first stopped asking the
+user to do the reflecting; it now also stops asking permission to keep it. The
+human is a reader and editor of the record, not a gate in front of it.
 
-### 1. Self-draft (always)
+## The flow
+
+### 1. Draft
 
 When a task is complete, draft **1–3** things genuinely worth remembering — a
 **decision**, a **gotcha**, or a **pattern** — from what happened this task. Each
@@ -22,47 +24,69 @@ item must be **concrete and cited**: name the files, PR, commands, or
 error-signatures it came from. **Skip entirely if nothing non-obvious happened**
 — an empty reflection is better than a filler one.
 
+That last rule is now the *only* filter. Nobody is going to catch a weak
+reflection before it lands, so do not record one.
+
 Pick the right `--kind` per item: `decision`, `gotcha`, `pattern`, `security`,
 `quality`, `intent`, `domain`, `integration`.
 
-### 2. Branch on run mode
+**Citing the files is not decoration — it is what makes the reflection findable.**
+Verity scopes a node to the paths named in its text, and retrieval seeds on that
+scope. A reflection that names no file in this repo is recorded and then never
+surfaces again, in any future review. So write `src/payments/retry.ts:88`, not
+"the retry path".
+
+### 2. Record it
 
-**Interactive** (a person is at the keyboard — a TTY): show your draft and ask
-one question before recording:
+```bash
+verity reflect --user-input "<your draft>" --kind <kind>
+```
 
-> "Here's my reflection draft for the project memory: _\<draft\>_. Anything to
-> **confirm, correct, or add** before I record it? (Say 'skip' to drop it.)"
+That is the whole step. It never blocks, never prompts, and works the same in a
+TTY, a hook, CI, or a cron run.
 
-Then record the **final** text — with their corrections folded in — via:
+If the reflection genuinely cannot name its files in prose, scope it explicitly:
 
 ```bash
-verity reflect --user-input "<final reflection>" --kind <kind>
+verity reflect --user-input "<your draft>" --kind <kind> --file-globs "src/auth/**"
 ```
 
-If they say "skip", do **not** record.
+The command warns when a reflection resolved to no files, so you will know when
+this is needed rather than discovering it months later as a node nobody read.
 
-**Autonomous** (no person to confirm — headless / CI / cron, or
-`VERITY_AUTONOMOUS=1`, or a non-TTY session): record your draft **directly**,
-never blocking:
+**When the *user* authored the words** — they said "record this: …", or dictated
+a lesson in their own terms — add `--confirmed`:
 
 ```bash
-verity reflect --user-input "<your draft>" --kind <kind> --autonomous
+verity reflect --user-input "<what they said>" --kind <kind> --confirmed
 ```
 
-Mode is auto-detected when you omit the flag (TTY ⇒ interactive, non-TTY ⇒
-autonomous); pass `--autonomous` to be explicit, or set `VERITY_AUTONOMOUS=0` to
-force a confirm step even in a headless run.
+This is not a formality. Without the flag a reflection is stored as
+`source: agent` (confidence 0.7) — *Verity thought this, nobody checked it*. With
+it, `source: user` at confidence 1.0 — *a person stands behind this*. The
+dashboard, the retrieval ranking, and the next agent to read the node all rely on
+the difference. Never pass `--confirmed` for your own draft, even a good one.
+
+### 3. Tell the user, in one line
+
+The command prints the node id, the local file path, and a dashboard link. Relay
+it — one line, no ceremony:
+
+> Recorded a gotcha about the Stripe retry path → `.verity/memory/gotchas/n104-stripe-idempotency-keys.md`
+
+They did not agree to this in advance, so they need to know it happened and where
+to go if it is wrong. Do not ask them to confirm it after the fact either — the
+file is right there, and editing or deleting it is the correction.
 
-### 3. Where it lands
+### 4. Where it lands
 
-The reflection is recorded **only to Verity's own memory namespace** —
-`.verity/memory/` (synced to the service). Verity never writes a repo's own
-`agents/memory` or any other store. One node per item; `source: 'user'`,
-`confidence: 1.0`, never auto-archived.
+Only Verity's own memory namespace — `.verity/memory/` (mirrored to the service).
+Verity never writes a repo's own `agents/memory` or any other store. One node per
+item, synced to disk immediately so it is readable and editable straight away.
 
 ## Auto-reflection (extract from task history)
 
-Complementary to the flip: trigger the server-side LLM extractor to mine the
+Complementary to the above: trigger the server-side LLM extractor to mine the
 current task's run history and produce 0–3 nodes. This is the same extraction
 that runs automatically on task close and every 5 runs — use it to trigger
 mid-task:
@@ -71,8 +95,8 @@ mid-task:
 verity reflect
 ```
 
-Use the self-draft flow above for the **compound moment** (a specific insight
-worth a confirmed node); use auto-extract to harvest what the run history shows.
+Use the draft flow above for the **compound moment** (a specific insight worth a
+node); use auto-extract to harvest what the run history shows.
 
 ## When to reflect
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/verity-cli",
-  "version": "0.32.5-experimental.4d91ca0",
+  "version": "0.32.6-experimental.833e71a",
   "description": "CLI for Verity quality gate service",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://verity.md",