Files
pipelines/docs/authoring-session-review.md
T
alan c42a19f7d3 Improve workflow UI, retain stage diffs, and add portable pipeline transfers
Make OpenCode authoring responsive and expand the managed skill references. Add conflict-aware import/export, real-provider reference workflows, and tracked V2 generation for reliable budget accounting.
2026-10-10 20:55:42 +01:00

79 lines
4.9 KiB
Markdown

# Authoring session review
## Observed in the supplied October 10 export
- The initial prompt contained a draft-context path and CLI prefix, but no edit
request. Before asking for intent, the agent made eight tool calls: skill load,
three file reads, and four CLI commands. It already recognized that a question
was needed, but continued investigating.
- Those CLI calls listed templates, called `show` without its required argument,
fetched an entire template already represented by the draft, and listed unrelated
retained drafts. None was needed to ask what should change.
- The question presented a generic feature menu instead of a direct edit question.
- After the user requested success/error notifications, the agent made twenty
discovery calls before its first edit: two globs, two shell commands, nine reads
and seven greps. It repeatedly debated adding model/native delivery stages.
Its format reference
pointed to project-local ntfy docs, causing a repository search and a long read
of installation, networking and phone setup information unrelated to this edit.
- The agent treated an optional native-publisher hint as a recommended design,
overlooking a minimal combination of existing stage hooks.
- It eventually chose the correct failure-only research hook and success/failure
report hook, validated the draft, and published version 2 after the user's explicit
approval. Those approval and immutable-version boundaries were respected.
- It also added a report attachment and renamed the output field from `report` to
`markdown` even though only a notification was requested. Its final summary
overstated this as a guarantee of exactly one notification per run; stage hooks
do not cover every cancellation/crash/limit failure or guarantee phone reception.
The export's creation/update times span 3m56s, including the user's reply. It has
no per-message/tool timestamps; it cannot establish time to first interaction or
separate inference, tool, network and user-wait latency.
## Changes
1. Launch prompts distinguish absent intent from an explicit request. With no
request they instruct OpenCode to ask first, before reads or CLI calls. With
a request they ask for a brief acknowledgement followed by targeted reading.
Launch remains one direct OpenCode command; no extra discovery or inference.
2. The skill puts intent before investigation and replaces generic questionnaires
with one open-ended question. After the reply it reads context, draft and only
relevant references. It preserves the authoritative CLI executable/URL prefix
and discourages speculative help calls, bare `show`, catalog comparisons,
unrelated draft listings and repeated unchanged reads.
3. A packaged `references/notifications.md` gives a self-contained decision guide:
hooks for ordinary alerts; native delivery only for explicitly routed delivery.
It includes the research/report terminal-path recipe, attachment requirements,
failure semantics and cancellation/crash/recovery-loop limitations. Attachments
and output-contract changes are added only when requested. No checkout
of Pipelines is needed during ordinary authoring.
4. Native-delivery examples use the system connection rather than suggesting a
second topic/token. Ordinary event alerts leave output contracts unchanged.
5. Skill installation includes the new reference and upgrades old managed
installations without overwriting modified files. Existing drafts, published
versions, schedules, tool permissions and approval boundaries are unchanged.
## Verification and limits
New-pipeline guidance also avoids asking for a name/stage count/model/tools before
understanding the task. It suggests one minimal graph and retains model inheritance,
loading optional notification/example references only when relevant. Regression
tests execute both new and edit launch commands against a stub executable and
check that each launches exactly once with ask-first guidance, without session,
help or API discovery. A command-preparation benchmark measures only local launch
preparation, not OpenCode startup or real-provider response latency.
`go test ./internal/author ./internal/server -run
'TestPrompt|TestCommandLaunches|TestInstalledSkill|TestSkillUpgrade|TestResearchTerminalNotificationRecipe'
-count=1` passed. These checks execute the captured launch command, inspect generated
prompts, upgrade the installed skill in an isolated directory, and execute the
research/report notification recipe against SQLite and a mock HTTP ntfy endpoint.
The recipe covers success, early/final blocked outcomes, early/final execution
errors and failed delivery without changing the run verdict or sending intermediate
success events.
The prompt/skill changes guide model behavior; they do not enforce a model's first
action. Real-provider time-to-first-question, compliance with the new instructions,
and actual phone reception are **not tested**. No new model inference or phone
message is needed to install these authoring changes.