[oliver-zehentleitner-aigent]

As discussed with the maintainer: this wires Keep the Why into picows so the reasoning behind the code is recorded next to it, and agents read it before they change things.

What is in the PR

AGENTS.md, split by kind. It carried two kinds of content: instructions for an agent working here (line width, Python 3.9, no del transport, no adapter plumbing, ...) and the reasoning behind picows' shapes. The instructions stay. The reasoning moves to context/ as entries with an explicit Evidence grade, and the affected bullets now point at the entry instead of restating it. Nothing was dropped; a new short "Why things are the way they are" pointer and the Keep the Why start section were added.

context/ — 11 entries in five topic files, plus the index and the three guard files the schema expects:

Entry	Evidence	Source
WSUpgradeRequest/WSUpgradeResponse keep a mixed bytes/str shape	confirmed	your AGENTS.md
Send-side calls after a CLOSE frame are no-ops	confirmed	your AGENTS.md, corroborated in picows.pyx
max_frame_size applies to non-control frames only	inferred	HISTORY 2.0.0 + the parser (which enforces 125, not 127)
No typing.cast in Cythonized hot paths	confirmed	your AGENTS.md
Protocol class: dummy Cython base first, asyncio.BufferedProtocol second	confirmed	your comment in picows.pyx
Buffered protocol instead of data_received	inferred	PR #69 title
aiofastnet optional; write path trusts its copy guarantee	confirmed	README + your comment in the write path
One C translation unit per SIMD instruction set	inferred	PR #96 + setup.py
Import-level compatibility with websockets	confirmed	your AGENTS.md, HISTORY 2.0.0
Upstream websockets is the behavioral source of truth	confirmed	your AGENTS.md
Wrapper-level workarounds for core inconsistencies are temporary and explicit	confirmed	your AGENTS.md
2.0.0 was a major version without breaking changes	confirmed	HISTORY 2.0.0

The three inferred entries say in their body that the reason is derived, not stated. If the derivation is right, flip them to confirmed; if it is wrong, correct or delete them — that is the whole point of the grade.

.keep-the-why — capture-confirmation: automatic (the skill records what a session establishes without asking each time) and a personal-defaults block (proactive capture, batch confirmation, checks every 14/30 days, linter auto-installed) so nobody has to answer the personal wizard question by question.

.github/workflows/ktw-lint.yml — structural lint of .keep-the-why and context/ on push and PR, via the rolling lint-latest action; warnings do not fail the job. Passes on this branch, --strict too.

CLAUDE.md — one line, @AGENTS.md, because Claude Code reads that file and not AGENTS.md.

What you need to do

Install the skill once for the agent you use. The preferred way is the skills CLI (runs via npx, Node.js required), pinned to the latest release; it asks which agent (Codex, Claude Code, OpenCode, ...) and which scope to install for:

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

If you prefer Codex's own plugin mechanism instead:

codex plugin marketplace add oliver-zehentleitner/keep-the-why
codex plugin add keep-the-why@keep-the-why

The first session on this repo asks one question, once per machine: whether to accept a project's suggested personal defaults automatically or be asked each time. After that it stays out of the way. With local-lint: auto it installs keep-the-why-lint from PyPI into your user environment the first time it writes to context/; set local-lint: ask or no in the personal-defaults block if you would rather not.

Then the experiment: don't think about it for two weeks. Entries accumulate as you work; the question is whether the agent's answers on picows get better because it reads context/ first.

Happy to adjust anything — entry wording, which bullets stay in AGENTS.md, the defaults.

[codspeed]

Merging this PR will degrade performance by 58.97%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 3 regressed benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_bench_echo[64]	355.5 ms	1,119.6 ms	-68.25%
❌	test_bench_echo[8192]	554 ms	1,437.6 ms	-61.47%
❌	test_bench_echo[32768]	1.2 s	2.1 s	-43.53%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing oliver-zehentleitner-aigent:keep-the-why (82ee159) with master (e7ae111)}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.96%. Comparing base (e7ae111) to head (82ee159).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #111   +/-   ##
=======================================
  Coverage   90.96%   90.96%           
=======================================
  Files          18       18           
  Lines        2590     2590           
  Branches      138      138           
=======================================
  Hits         2356     2356           
  Misses        191      191           
  Partials       43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.