Skip to content

fix(productivity): explain software behavior through user examples - #17

Merged
christso merged 1 commit into
mainfrom
fix/write-naturally-concrete-explanations
Nov 16, 2026
Merged

christso merged 1 commit into
mainfrom
fix/write-naturally-concrete-explanations

Conversation

@christso

Copy link
Copy Markdown
Contributor

Summary

When someone asks why saving a shared document failed, the explanation should start with their attempted save and the refusal they saw. The skill previously made examples optional and waited for a plain-English request before checking unexplained shorthand, so a reply could start with terms such as "authorization preflight" and leave the reader asking for another explanation.

The skill now starts software explanations with a recognizable user action and result, then carries that same example through the cause and the fix. It introduces internal terms when they help explain the example and adapts when the reader already knows the context or asks for implementation detail.

Added a fictional shared-document case to the existing writing evals. It checks that the reply explains the failed save concretely while preserving the limits: valid team access allows saving, revoked access stays revoked, saving without active access remains denied, and no content was lost.

Validation

  • bun run validate: both catalogues and local Markdown references passed.
  • bun test: 58 passed, 0 failed; 292 assertions.
  • Skill frontmatter validation and git diff --check: passed.
  • An independent agent read the revised skill and wrote the shared-document explanation from raw source facts. The reply began with the failed save, explained the permission check and fix, and retained all supplied access and data-preservation limits. This was a manually assessed behavioral smoke check.
  • Promptfoo 0.124.1 loaded the new case, but its configured gpt-6.1-sol target was rejected by the local Codex SDK account. That run had 1 provider error and no graded results; no Promptfoo quality pass is claimed. Saved model settings were left intact.

@christso
christso merged commit 26e89fd into main Nov 16, 2026
1 check passed
@christso
christso deleted the fix/write-naturally-concrete-explanations branch November 16, 2026 05:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant