nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/skills/nobrainer-writing/references/brief-artifacts.md

@@ -0,0 +1,357 @@
+# Brief artifacts
+
+Use this reference only for the `BRIEF` mode of `nobrainer-writing`. Pick one
+artifact and keep the output small enough that a busy reader can decide or act
+without reconstructing the story.
+
+## The common shape
+
+```text
+Title: <observable failure or user outcome>
+Problem or goal: <one sentence>
+Impact or value: <who is affected and why it matters>
+Evidence or context: <reproduction, example, link, version, or UNKNOWN>
+Acceptance or question: <how we know what to do or what answer is needed>
+Next action: <one owner/action, if relevant>
+```
+
+Use only fields that change triage or implementation. Do not add a history
+section, root-cause theory, solution design or generic closing unless the reader
+needs it to act. Facts from the requester outrank polished wording; unknowns
+stay visible.
+
+Task-shaped artifacts (`BUG`, `ISSUE`, `USER_STORY` and `REQUEST`) always expose
+two fields:
+
+- `Description`: what is wrong, needed or intended.
+- `Definition of Done (DoD)`: the observable closure condition and required proof.
+
+Keep `Acceptance` for observable product behavior; do not hide the description or
+DoD inside `Problem`, `Context`, `Done when` or a generic paragraph. `COMMENT`
+is intentionally smaller and does not need task fields.
+
+Number every acceptance criterion sequentially as `AC01`, `AC02`, `AC03` and so
+on. Start at `AC01`, do not leave gaps, and do not use anonymous bullets or
+checkboxes under `Acceptance`. DoD remains separate and may reference the AC IDs.
+
+Before compressing, keep a private ledger of material facts: when it started,
+what did or did not happen, exact statuses/errors, conditions, uncertainty and
+the requested action. A concern is not proof of a failure, and a request to know
+whether something is safe is not permission to invent the policy that decides
+it. If the source does not define the desired behavior, write the open decision
+or `UNKNOWN` instead of adding a warning, retry rule, UI state or implementation.
+
+## COMMENT
+
+Use for code review, issue updates, decisions, questions and status. Start with
+the observation or decision, then the impact, evidence and one request.
+
+```text
+ENV: <Name> | URL: <route or N/A> | User: <role or redacted alias>
+<Observation or decision>. <Why it matters or what changed>.
+<Requested action or question>.
+Evidence: <file, line, test, link or concrete example>.
+```
+
+Good code-review comment:
+
+> ENV: TEST | URL: N/A | User: reviewer
+>
+> This returns `200` when the provider times out, so the caller treats a failed
+> sync as success. Return the error or mark the result `UNKNOWN`, and add a
+> timeout test; evidence: `sync_provider()` line 84 and the missing-timeout test.
+
+Good status comment:
+
+```text
+ENV: QA | URL: https://demo.example.test/runs/42 | User: qa-operator
+The timeout is now reported as a failed sync, and test `provider_timeout_marks_failure` passes. Next: review the PR.
+```
+
+Do not turn a comment into a mini-report. If there is no concrete observation,
+write a direct question instead of praise followed by a vague suggestion.
+
+## BUG
+
+Title the observable failure, not a guessed cause.
+
+````text
+Title: [Bug] <what fails> when <condition>
+
+Description: <one sentence describing the failure>
+
+ENV:
+- Name: <QA | DEV | TEST | PROD | PREPROD | BETA | UNKNOWN>
+- URL: <exact non-secret route or page, or N/A when no URL applies>
+- User: <role or redacted/synthetic alias, never a credential>
+- Build/client: <release, client, OS, deployment or UNKNOWN, when useful>
+
+Steps to reproduce:
+1. <setup>
+2. <action>
+3. <result>
+
+Current behavior: <what happens now>
+Expected behavior: <what should happen>
+
+API request (cURL), when applicable:
+```bash
+# Complete redacted curl command: method, URL, headers and body.
+```
+
+API response, when applicable:
+```http
+# Status, headers and body.
+```
+
+Database query (read-only), when applicable:
+```sql
+-- Read-only query.
+```
+
+Database result, when applicable:
+```text
+# Observed result; use its actual format when useful.
+```
+
+Evidence, for a UI screenshot or MP4 recording, when applicable: <attach file>
+HAR, only when the page-load/request chain matters: <attach file or N/A>
+
+Definition of Done (DoD): <observable regression proof and required checks>
+````
+
+`Description`, `ENV:`, `Steps to reproduce`, `Current behavior` and
+`Expected behavior` are separate diagnostic fields. `ENV:` keeps the
+environment name, exact URL and user used together; its optional `Build/client`
+line preserves useful release or client context. Surface-proof sections remain separate
+and appear only when applicable. Keep `URL` as `N/A` for a worker, CLI
+or other flow with no page to open. Use `UNKNOWN` when the requester does not
+know a value; do not replace a missing value with a guess.
+
+Proof must match the affected surface:
+
+- **API:** include a complete redacted `curl` request in one fenced `bash` block
+  and the response in a separate fenced `http` block. Keep method, URL, all
+  captured headers, body, status and response body; redact sensitive values
+  without changing the request's material shape.
+- **Database:** include the read-only query and result in separate fenced blocks;
+  use `sql` for the query and the result's actual format when useful.
+- **UI:** put a screenshot or an MP4 recording in `Evidence`. If the failure
+  depends on the page-load/request chain, attach a HAR too; keep the exact URL
+  and reproduction steps in the report.
+
+When a bug crosses more than one surface, include each applicable proof pair or
+artifact. Do not collapse them into a generic `Evidence` paragraph. A URL or
+prose description alone does not replace UI evidence. If required proof is not
+supplied, return `INPUT_REQUIRED` and identify what is missing instead of drafting
+a report with weaker substitute evidence.
+
+Example:
+
+````text
+Title: [Bug] Sync reports success after a provider timeout
+
+Description: A timeout leaves the sync marked as successful.
+
+ENV:
+- Name: TEST
+- URL: N/A (worker-only reproduction)
+- User: sync-test-user
+- Build/client: release 1.3.0, local worker, macOS, staging provider
+
+Steps to reproduce:
+1. Start a sync against a provider that does not answer.
+2. Wait for the request timeout.
+3. Open the run history.
+
+Current behavior: The UI shows “success” and no retry is scheduled.
+Expected behavior: The run is marked failed or explicitly unknown.
+
+Database query (read-only):
+```sql
+SELECT status, error FROM sync_runs WHERE id = 42;
+```
+
+Database result:
+```text
+status=success, error=timeout
+```
+
+Definition of Done (DoD): A regression test proves timeout is not reported as
+success, and any retry behavior in scope is explicitly agreed and covered.
+````
+
+Leave the suspected root cause out unless it is verified. A useful bug report
+lets another person reproduce the behavior without a meeting.
+
+## ISSUE
+
+Use for a feature, workflow improvement or change request. Keep `Description` to
+one sentence, then use only the fields that help someone decide or build it.
+
+```text
+Title: [Feature] <user outcome>
+
+Description: <what is hard, missing or unreliable today>
+Who is affected: <specific user or workflow>
+Desired outcome: <what the user can do or rely on afterwards>
+Evidence: <example, frequency, user wording or link>
+
+Acceptance:
+- [ ] AC01: <observable pass/fail result>
+- [ ] AC02: <observable edge case or failure result>
+- [ ] AC03: <proof or compatibility condition, if relevant>
+
+Definition of Done (DoD):
+- [ ] <acceptance criteria pass in the affected surface>
+- [ ] <required tests/checks and proof are attached or linked>
+```
+
+Example:
+
+```text
+Title: [Feature] Show why a sync was not retried
+
+Description: A failed run only says “failed”, so it is unclear whether the next
+run is safe to start.
+Who is affected: Operators checking a failed scheduled sync.
+Desired outcome: The run shows whether the failure is retryable and what to do.
+Evidence: The current log contains the error, but the run history does not.
+
+Acceptance:
+- [ ] AC01: Retryable failures show “retryable” and the next retry time.
+- [ ] AC02: Non-retryable failures show “manual action required”.
+- [ ] AC03: The existing error detail remains available for diagnosis.
+
+Definition of Done (DoD):
+- [ ] The three acceptance criteria pass in the run-history UI.
+- [ ] Automated coverage and the verification result are attached to the issue.
+```
+
+## USER_STORY
+
+Use the user's goal, not a UI control or implementation task. The familiar
+persona/goal/value sentence is useful, but the acceptance criteria decide what
+counts as complete.
+
+Derive acceptance from the stated goal. If the source gives only a concern or a
+question, keep the criterion at that level and name the missing decision; do not
+invent a product policy to make the story look complete. Use `Given/When/Then`
+only when it improves verification or matches the team's existing language.
+
+```text
+Title: <short user outcome>
+
+Description: <real problem, context or constraint behind the goal>
+
+As a <specific user>, I want <goal> so that <value>.
+
+Context: <real situation or constraint, if needed>
+Acceptance:
+- AC01: Given <context>, when <action>, then <observable result>.
+- AC02: <another independent pass/fail result>
+
+Definition of Done (DoD):
+- [ ] <the acceptance criteria pass for the named user>
+- [ ] <required tests/checks and proof are attached or linked>
+
+Out of scope: <important boundary, if needed>
+```
+
+Example:
+
+```text
+Title: Explain failed scheduled syncs
+
+Description: Operators currently see a failed run without knowing whether it is
+safe to retry.
+
+As an operator, I want to know whether a failed sync can be retried so that I
+do not duplicate data or leave a delivery gap.
+
+Acceptance:
+- AC01: Given a timeout, when I open the run, then it is marked retryable and shows
+  the next retry time.
+- AC02: Given an authentication failure, when I open the run, then it is marked
+  “manual action required”.
+
+Definition of Done (DoD):
+- [ ] Timeout and authentication scenarios pass in the run-history UI.
+- [ ] The verification result is attached and the existing error detail remains
+  available.
+```
+
+Do not force the `As a / I want / so that` form when the real request is a bug,
+decision or operational task. A plain one-sentence outcome is better than a
+ceremonial story that hides the need.
+
+## REQUEST
+
+Use for a short ask to a person or team:
+
+```text
+Description: <what needs to change or be produced, and why>
+Request: <one concrete action>
+Why: <one sentence of context>
+Input or location: <file, link, example or attachment>
+Needed by: <date only when real>
+Definition of Done (DoD): <the exact output and proof the requester can verify>
+```
+
+Example:
+
+```text
+Description: The issue template does not tell reporters what proof is required
+for API, database and UI failures.
+Request: Update the public bug template with separate copyable proof fields.
+Why: Reporters should be able to paste the evidence without reconstructing it.
+Input or location: .github/ISSUE_TEMPLATE/bug_report.md
+Needed by: 2026-09-02
+Definition of Done (DoD): The template has separate request/response, query/result
+and UI/HAR fields, and the repository checks confirm their order.
+```
+
+## Human-feel and compression gate
+
+Keep:
+
+- exact product, file, error and user terms;
+- the writer's real stance, uncertainty and concrete example;
+- one clear ask or next action;
+- enough context to reproduce or decide.
+
+Cut:
+
+- greetings, praise and “I would like to kindly…” before the point;
+- “improve the experience”, “make it robust” and similar goals without a
+  measurable result;
+- invented metrics, root causes, personas, urgency or agreement;
+- repeated summaries, generic conclusions and implementation detail the reader
+  did not request.
+
+Never add mistakes, random slang or fake personal experience to make text seem
+human. Naturalness comes from concrete source material and restrained editing.
+
+Before returning, check:
+
+```text
+ACTIONABLE: PASS | FAIL
+FACTS_TRACEABLE: PASS | FAIL
+EXPECTED_OR_DESIRED_CLEAR: PASS | FAIL
+ACCEPTANCE_OR_QUESTION_CLEAR: PASS | FAIL | NOT_APPLICABLE
+NO_INVENTED_CAUSE_OR_CONTEXT: PASS | FAIL
+LOW_VALUE_SENTENCES_REMOVED: PASS | FAIL
+```
+
+Return `INPUT_REQUIRED` if a failed check would require invention.
+
+## Research basis
+
+Checked 2026-09-02. These are design inputs, not copied platform templates:
+
+- [GitHub issue and pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) supports reusable guidance and structured issue forms.
+- [GitHub issue form configuration](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) shows required fields and separate expected/actual evidence; the public form schema is platform-specific, so this skill remains Markdown-first.
+- [GitLab Documentation Style Guide](https://docs.gitlab.com/development/documentation/styleguide/) emphasizes concise, direct, precise, searchable and conversational-but-brief writing.
+- [Digital.gov: Writing for understanding](https://digital.gov/guides/plain-language/writing) recommends audience-specific language, short sections and active responsibility.
+- [Atlassian: User stories](https://www.atlassian.com/agile/project-management/user-stories) connects persona, goal, value and acceptance criteria; its 3 Cs are Card, Conversation and Confirmation.
+- [hannsxpeter/humanizer](https://github.com/hannsxpeter/humanizer/blob/main/SKILL.md) recommends preserving an authentic voice and making minimal edits when the input already sounds human; it explicitly rejects detector gaming.

package/skills/nobrainer-writing/references/plain-technical-english.md

@@ -0,0 +1,76 @@
+# Plain technical English
+
+Default to Writing's `TECHNICAL` mode for English specifications, instructions,
+runbooks and technical explanations when no other mode is requested. Infer the profile from the artifact:
+`PROCEDURE` for actions, `EXPLANATION` for understanding. A mixed document can
+use both. Apply plain, precise language to ordinary replies too, without adding
+a procedural template. Keep marketing and other requested voices appropriate
+to their purpose. Write directly in the requested language; non-English output
+uses natural grammar and the same meaning checks, not the English dictionary
+or a mandatory translation pass. A technical product alone does not make an
+artifact technical documentation.
+
+This is an independent writing adaptation informed by
+[ASD-STE100](https://www.asd-ste100.org/about_STE.html) and
+[Karpathy's suggestion](https://x.com/karpathy/status/2105819303471976479).
+It does not reproduce the standard or dictionary, check all its rules, or
+claim official approval, certification or full conformance. A formal STE
+request requires the current official standard, domain terminology and
+qualified review; this mode alone cannot establish compliance.
+
+## Preserve meaning before simplifying
+
+Use Writing's meaning ledger. Freeze commands, code, identifiers, quotations,
+links, numbers, units, scope, sequence, permission strength, negation,
+uncertainty and safety conditions. Keep `may`, `must` and `should` distinct.
+Do not split a condition away from the action it restricts or change `and` to `or`.
+Do not invent the actor, test result or missing step to make a sentence cleaner.
+Mandatory quoted wording remains verbatim; simplify its surrounding explanation.
+
+Choose one name per concept from the project's terminology. Define an unfamiliar
+term once if the reader needs it. Keep precise domain terms and technical verbs;
+do not replace them with a common but less accurate word. There is no automatic
+forbidden-word list, synonym substitution or ban on words ending in `-ing`.
+
+## PROCEDURE: make the next action clear
+
+- Put prerequisites and safety conditions before the action they govern.
+- Give each step one action. Use a direct command when the source is an
+  instruction; preserve optional actions and permissions as optional.
+- Prefer short sentences, with a 20-word target for newly written prose.
+  Split for comprehension, never by cutting a command, condition or caveat.
+- Keep the original order when it changes behavior. State the expected result
+  only when supported. Keep recovery instructions with their trigger.
+
+## EXPLANATION: make the mechanism clear
+
+- State the result or concept, then explain the cause, limitation or consequence.
+- Prefer short sentences, with a 25-word target and one topic per paragraph.
+- Use active voice when the actor is known. Keep passive voice when the actor
+  is unknown or naming one would invent a fact.
+- Use a small example or diagram only when it resolves a concrete ambiguity.
+  Do not produce a diagram, interactive page or video for every explanation.
+
+Sentence targets are editing aids, not pass/fail limits for this adaptation.
+Code, exact quotations and necessary technical terms can exceed them. Do not
+claim official STE compliance from word counts or a few regex checks.
+
+## Verify the rewrite
+
+Compare every ledger item with the result. Check especially combined conditions,
+exceptions, optional versus mandatory actions, unknown actors and unverified
+outcomes. A shorter text fails if its meaning changes. Restore necessary detail
+before returning it; ask only when the source itself is materially ambiguous.
+
+Return the finished text by default. If an audit is requested, state the profile,
+meaning-check result and any unresolved source ambiguity. Report words or tokens
+only if measured. A word-count reduction does not prove cheaper tasks, better
+models, safer operation or official conformance.
+
+## Source boundaries
+
+Reviewed 2026-10-02: [official FAQ](https://www.asd-ste100.org/STE_faq.html)
+distinguishes procedures from descriptions and permits passive descriptions
+when the actor is unknown. The [official tools page](https://www.asd-ste100.org/STEsoftware.html)
+does not make a language checker a substitute for the standard. Karpathy
+recommends an existing method; he did not invent it or supply a Flow benchmark.

package/skills/nobrainer-writing/references/research.md

@@ -0,0 +1,86 @@
+# Research basis for high-signal writing
+
+Research question: which current writing methods best reduce generic AI prose
+and word count without losing meaning, evidence, audience fit or safety?
+
+Decision supported: define one portable writing skill for messages, comments,
+documentation, reports and longer content. Every source was accessed on
+2026-08-28. Repository sources are pinned below; publisher documentation remains
+a live URL, so no immutable snapshot or unshown publication date is claimed.
+
+## Ten approaches reviewed
+
+| # | Source and provenance | Useful approach | Limitation carried into the skill |
+|---|---|---|---|
+| 1 | [blader/humanizer 2.11.2](https://github.com/blader/humanizer/blob/38b88903a5080c72a8c0472e79dcc9ffbf07938b/SKILL.md); commit `38b8890` dated 2026-08-19, Git blob `c9c2242`, accessed 2026-08-28 | Preserve every claim, never invent facts, and let a real writing sample override generic style rules. | A long pattern catalogue is useful for audit but too heavy for every ordinary draft; punctuation and vocabulary are contextual, not proof of authorship. |
+| 2 | [hannsxpeter/humanizer 1.2.1](https://github.com/hannsxpeter/humanizer/blob/c35d49f5d57ed6e2222c23fab22b30e34ffa79e5/SKILL.md); commit `c35d49f` dated 2026-08-16, Git blob `b5bad0d`, accessed 2026-08-28 | Treat voice matching and conservative editing as the goal, with explicit false-positive restraint. | Do not frame quality work as beating detectors or disguising authorship. |
+| 3 | [Concise Output 1.2.0](https://github.com/jagreehal/jagreehal-claude-skills/blob/810e8d69ef23476f15f3f5ee1044b9552a9fdba0/skills/concise-output/SKILL.md); commit `810e8d6` dated 2026-07-29, Git blob `f0e528f`, accessed 2026-08-28 | Put the point first, delete filler and test whether each sentence earns its place. | Extreme brevity needs exceptions for teaching, trade-offs, safety and long-form argument. |
+| 4 | [Microsoft: simple words and concise sentences](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences); live publisher page accessed 2026-08-28 | Use precise simple words, remove words without substance and keep text scannable. | Simple must not become abrupt, vague or less accurate. |
+| 5 | [Google developer documentation: voice and tone](https://developers.google.com/style/tone); live publisher page accessed 2026-08-28 | Write clearly, directly and naturally for a global audience; avoid buzzwords, canned phrases and unnecessary entertainment. | Conversational writing is not a transcript of speech and should not import slang or cultural references by default. |
+| 6 | [Digital.gov plain-language guide](https://digital.gov/guides/plain-language/writing) and [18F plain language](https://guides.18f.org/content-guide/our-approach/plain-language/); both live publisher pages accessed 2026-08-28 | Start from the specific audience, use active responsibility where useful, short sections and familiar literal terms. | Plain language is audience-relative; specialist readers may need precise technical terms. |
+| 7 | [Mailchimp content style guide](https://styleguide.mailchimp.com/grammar-and-mechanics/); live publisher page accessed 2026-08-28 | Build an information hierarchy, lead with the main point, stay specific and adapt tone to the reader and channel. | Friendly voice never outranks clarity, truth or the reader's emotional context. |
+| 8 | [GitLab documentation style guide](https://docs.gitlab.com/development/documentation/styleguide/); live publisher page accessed 2026-08-28 | Make documentation concise, direct, precise, task-oriented and easy to search or scan; avoid sales claims and self-reference. | Documentation structure differs from email, social and long-form prose, so one fixed template would overfit. |
+| 9 | [IBM Carbon writing style](https://carbondesignsystem.com/guidelines/content/writing-style/); live publisher page accessed 2026-08-28 | Trim to as few words as possible without becoming terse, and vary tone with the user's journey and task. | Word count alone cannot judge usefulness; context and comprehension remain the acceptance test. |
+| 10 | [W3C writing for web accessibility](https://www.w3.org/WAI/tips/writing/); live publisher page accessed 2026-08-28 | Use clear sentences, meaningful headings and links, expanded acronyms and structure that remains understandable to assistive technology. | Compression must not remove orientation or make meaning depend on visual layout. |
+
+## Facts, inference and decision
+
+`FACT`: Across maintained corporate, government and accessibility guidance, the
+recurring practices are audience-first purpose, front-loaded information,
+simple precise language, useful structure, active responsibility, consistent
+terms and removal of unsupported or repetitive prose.
+
+`FACT`: The reviewed humanizer skills add two valuable safeguards: preserve a
+meaning ledger and use an authentic voice sample instead of injecting generic
+"human" quirks.
+
+`INFERENCE`: AI slop is primarily a relevance, structure and evidence problem.
+A word blacklist can help detect clusters, but it cannot establish quality and
+creates false positives when applied as a hard ban.
+
+`INFERENCE`: A literal 80% reduction is unsafe as a universal acceptance rule.
+The transferable Pareto principle is to protect decision-relevant value and
+remove low-value ceremony until every remaining sentence earns its place.
+
+`DECISION`: Use one lightweight protocol with a frozen content contract, a
+structure-first compression pass, an integrity checksum, artifact-specific
+shapes and final-only output. Keep detailed research outside `SKILL.md` so an
+ordinary invocation pays only for operational guidance.
+
+## Rejected patterns
+
+- deliberate grammar errors, fake anecdotes or random slang as evidence of
+  humanity;
+- optimizing for an AI detector or claiming human authorship;
+- hard bans on punctuation, sentence length or individual vocabulary;
+- a mandatory before/after report that makes every short answer longer;
+- compression ratios that override facts, caveats, accessibility or action.
+
+
+## Plain technical English adaptation — 2026-10-02
+
+[Karpathy's original post](https://x.com/karpathy/status/2105819303471976479)
+recommends the existing ASD-STE100 method for readable explanations, and choosing
+diagrams or interactive artifacts when they aid understanding. It is a writing
+suggestion, not a measured performance result for Flow.
+
+The [official overview](https://www.asd-ste100.org/about_STE.html) describes a
+controlled language with rules and a dictionary. The
+[official FAQ](https://www.asd-ste100.org/STE_faq.html) distinguishes procedural
+and descriptive text, including passive descriptions when the actor is unknown.
+Writing adopts independently phrased clarity guidance in
+[plain technical English](plain-technical-english.md), with a meaning ledger and
+explicit limits. It does not ship the dictionary, certify conformance or infer
+token/cost savings. The existing contextual anti-slop rules remain in force for
+other modes and languages.
+
+
+### Default communication refinement — 2026-10-02
+
+Owner-requested policy: use plain technical English for operational exchanges
+between agents, while user-facing replies keep the requested language. This is
+a design default, not evidence that English improves every model or reduces
+tokens. The factual contract is shared; a second translation call is not required.
+English technical artifacts select TECHNICAL when no mode is requested. Other
+languages use natural plain language with the same meaning-preservation checks.
+Caller schemas, quoted text and explicit language/voice requests remain binding.