From c68b45a1e0596b83c5fff447e75cef4e85d10fc2 Mon Sep 17 00:00:00 2001 From: Jean Mertz Date: Fri, 29 May 2026 14:01:17 +0200 Subject: [PATCH] chore: Update knowledge base and persona config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new "caller-context leak" anti-pattern to the code-comments knowledge file. Doc comments describe what a function promises to any caller; justifying that promise in terms of one specific caller's situation (e.g. `--check` mode, a wizard's flow) leaks context that the reader doesn't have. The contract should be stated on its own terms, with caller-specific reasoning reserved for a `//` comment at the call site. A good/bad example pair illustrates the distinction. The forbidden-words list in the default persona is tightened: the escape clause ("unless there is a very good reason") is removed, and two new entries are added — `load-bearing` and `*em dashes*` — keeping the list consistent with observed failure patterns. Also corrects the architecture knowledge file to reflect that JP is now developed by three human authors rather than one. Signed-off-by: Jean Mertz --- .jp/config/knowledge/architecture.toml | 2 +- .jp/config/knowledge/code-comments.toml | 37 +++++++++++++++++++++++++ .jp/config/personas/default.toml | 7 +++-- 3 files changed, 42 insertions(+), 4 deletions(-) diff --git a/.jp/config/knowledge/architecture.toml b/.jp/config/knowledge/architecture.toml index 34c934a1..a53c0914 100644 --- a/.jp/config/knowledge/architecture.toml +++ b/.jp/config/knowledge/architecture.toml @@ -86,7 +86,7 @@ about programming like it is about writing code, but the code ends up being less important than the architecture, and the architecture ends up being less important than \ social issues." -For JP specifically, the "social structure" is one human author working with a small \ +For JP specifically, the "social structure" is three human authors working with a small \ set of AI agents (`dev`, `architect`, `rfd-reviewer`, `committer`, …), each constrained \ by a persona. The architecture reflects this: diff --git a/.jp/config/knowledge/code-comments.toml b/.jp/config/knowledge/code-comments.toml index a23f451c..8303e00f 100644 --- a/.jp/config/knowledge/code-comments.toml +++ b/.jp/config/knowledge/code-comments.toml @@ -91,6 +91,14 @@ been produced in this project and corrected. own terms; if the contrast actually matters for using the item, restate \ the relevant fact directly. +- **Caller-context leak.** A doc comment describes what the function \ + promises to *any* caller. Don't justify the promise in terms of one \ + particular caller's situation — "so that `--check` mode exits non-zero", \ + "because the CLI prints this", "to keep the wizard's flow correct". The \ + reader of the doc comment doesn't know about the wizard or `--check`. \ + State the contract on its own terms; the caller-specific reasoning \ + belongs in a `//` comment at the call site. + - **Restating the signature.** `/// Returns the user's name.` on \ `fn name() -> String` adds nothing. Either say what isn't visible \ (where the value comes from, what happens on the unset path, ownership, \ @@ -125,6 +133,11 @@ items = [ State what it does on its own terms.\ """, """\ + **Don't justify a function's behavior with caller context.** State the \ + contract on its own terms; caller-specific reasoning belongs at the \ + call site.\ + """, + """\ **Don't ship stale inline comments.** Update the invariant or delete \ the line — never both wrong and ignored.\ """, @@ -198,6 +211,30 @@ function. The good version describes the contract directly; the contrast \ with `read` is implicit and stays out of the way.\ """ +[[assistant.instructions.examples]] +good = """\ +/// Walk the tree under `root` and return every `.rs` file. +/// +/// Walker errors (unreadable directories, symlink loops, etc.) are +/// propagated rather than silently skipped. +fn walk_rust_files(root: &Path) -> Result, Error> { ... }\ +""" +bad = """\ +/// Walker errors (unreadable directories, symlink loops, etc.) are +/// propagated rather than silently skipped: in `--check` mode a swallowed +/// error would let the job exit 0 without having checked the file the +/// user asked about. +fn walk_rust_files(root: &Path) -> Result, Error> { ... }\ +""" +reason = """\ +The bad version makes the function's contract depend on the reader \ +knowing about `--check` mode — but `walk_rust_files` doesn't know about \ +`--check` mode; only one of its callers does. The good version states \ +the contract on its own terms (errors propagate, period). The \ +`--check`-mode reasoning belongs in a `//` comment at the call site, \ +where the reader is already in that world.\ +""" + [[assistant.instructions.examples]] good = """\ // Sorted by created_at upstream; the binary search below depends on it. diff --git a/.jp/config/personas/default.toml b/.jp/config/personas/default.toml index 051cc3aa..deefcf07 100644 --- a/.jp/config/personas/default.toml +++ b/.jp/config/personas/default.toml @@ -307,9 +307,10 @@ response style. Simply answer the query appropriately. position = -90 tag = "forbidden_words" content = """ -You MUST NOT use these words or phrases in your responses, unless there is a -very good reason to do so: +You MUST NOT use these words or phrases in your responses: - comprehensive -- "key insight" +- key insight +- load-bearing +- *em dashes* """