@rmrdeveloper/sideroom-pi 8.10.0 → 8.12.0

package/skills/sideroom-guidelines/references/languages/javascript.md

@@ -249,7 +249,7 @@ async function createUser(userInput) {
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```js
 // bad — extracted after one use
@@ -264,7 +264,7 @@ function normalizeTicketStatus(status) {
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```js
 // bad
@@ -279,7 +279,7 @@ function formatPrice(value) {
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```js
 // bad
@@ -382,3 +382,25 @@ setInterval(checkPaymentStatus, 5_000);
 **When in doubt:** fail fast, keep it flat, keep it small.
 
 **Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+
+## Language-specific conventions
+
+### Destructured function parameters
+
+When a function would take 3 or more parameters, accept one object and destructure its named properties in the parameter list. Count optional and defaulted parameters toward the threshold. Functions with 1 or 2 parameters may keep positional parameters.
+
+Keep signatures imposed by external APIs, framework callbacks, overrides, or public compatibility contracts; use a destructured internal helper when it makes the implementation clearer. When changing a signature you own, update its callers together. Do not rewrite unrelated functions only to satisfy this convention.
+
+```js
+// bad
+function createInvoice(order, currency, dueDate) {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+// good
+function createInvoice({ order, currency, dueDate }) {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+createInvoice({ order, currency: 'USD', dueDate });
+```

package/skills/sideroom-guidelines/references/languages/php-laravel.md

@@ -153,7 +153,7 @@ function create(ValidatedUser $input): User { $user = $this->normalizer->normali
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```php
 // bad — extracted after one use
@@ -164,7 +164,7 @@ function normalizeTicketStatus(string $status): TicketStatus { return TicketStat
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```php
 // bad
@@ -175,7 +175,7 @@ function formatPrice(float $value): string { return '$'.number_format($value, 2)
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```php
 // bad

package/skills/sideroom-guidelines/references/languages/python.md

@@ -205,7 +205,7 @@ def create_user(validated_payload, repository):
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```python
 # bad — extracted after one real use
@@ -218,7 +218,7 @@ def normalize_ticket_status(status):
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```python
 # bad
@@ -231,7 +231,7 @@ def format_price(value):
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```python
 # bad

package/skills/sideroom-guidelines/references/languages/rust.md

@@ -155,7 +155,7 @@ fn create(input: ValidatedInput, repo: &impl Repo) -> Result<User> { let user =
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```rust
 // bad — extracted after one use
@@ -166,7 +166,7 @@ fn normalize_ticket_status(status: &str) -> Result<TicketStatus> { status.trim()
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```rust
 // bad
@@ -177,7 +177,7 @@ fn format_price(value: f64) -> String { format!("${value:.2}") }
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```rust
 // bad

package/skills/sideroom-guidelines/references/languages/typescript.md

@@ -154,7 +154,7 @@ async function create(input: ValidatedUser): Promise<User> { const user = normal
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```ts
 // bad — extracted after one use
@@ -165,7 +165,7 @@ const normalizeTicketStatus = (status: string): TicketStatus => parseTicketStatu
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```ts
 // bad
@@ -176,7 +176,7 @@ function formatPrice(value: number): string { return `$${value.toFixed(2)}`; }
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```ts
 // bad
@@ -247,3 +247,27 @@ setInterval(checkPaymentStatus, 5_000);
 **When in doubt:** fail fast, keep it flat, keep it small.
 
 **Enforcement note:** rules 1–2 are mechanical and should be backed by TypeScript formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+
+## Language-specific conventions
+
+### Destructured function parameters
+
+When a function would take 3 or more parameters, accept one object and destructure its named properties in the parameter list. Count optional and defaulted parameters toward the threshold. Functions with 1 or 2 parameters may keep positional parameters. In TypeScript, type the object with a named type or interface.
+
+Keep signatures imposed by external APIs, framework callbacks, overrides, or public compatibility contracts; use a destructured internal helper when it makes the implementation clearer. When changing a signature you own, update its callers together. Do not rewrite unrelated functions only to satisfy this convention.
+
+```ts
+// bad
+function createInvoice(order: Order, currency: string, dueDate: Date): Invoice {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+// good
+type InvoiceInput = { order: Order; currency: string; dueDate: Date };
+
+function createInvoice({ order, currency, dueDate }: InvoiceInput): Invoice {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+createInvoice({ order, currency: 'USD', dueDate });
+```

package/skills/sideroom-persona/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-persona
-description: "Apply Sideroom's single built-in persona: the voice rules and hard prohibitions every user-facing answer must follow. Load it when an explanation, summary, or report needs the full guide. Do not use for code-only mutations that need no prose."
+description: "Write and revise user-facing prose in Sideroom's direct, plain voice. Load the complete guide before the first substantial explanation, findings report, implementation summary, or user-facing documentation, and when the user requests clearer, shorter, or less technical wording. Apply it to progress messages and final answers. Brief acknowledgments can use the always-on reminder; reuse the guide while it remains in context."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -15,44 +15,57 @@ the complete guide.
 
 ## Activation Contract
 
-Read this whole file with `read`, without `offset` or `limit`, when an answer
-needs the full persona instead of the injected reminder.
+Before the first substantial explanation, findings report, implementation
+summary, or user-facing documentation, load this complete guide through
+`sideroom_persona` or read this whole file without `offset` or `limit`. Also
+load it when the user asks for clearer, shorter, or less technical wording.
+Reuse it while it remains in context; reload it after compaction if the guide
+is no longer available. Brief acknowledgments use the always-on reminder.
+
+Apply the voice to progress messages and final answers. Before sending prose,
+check that the answer starts with the outcome, explains only necessary
+technical terms, and avoids repetition, invented labels, and filler. Keep
+evidence, exact commands, uncertainty, and requested detail when needed;
+plain language must not remove facts.
 
 ## Voice rules
 
 | # | Rule | Do | Don't |
 | --- | --- | --- | --- |
-| 1 | Plain, never in doubt | `Enable the flag to skip cache (enableCache).` | `The registry resolves the provider through the auth resolver pipeline.` |
-| 2 | Direct and dry | `The guard blocks the write. Fix the emoji and retry.` | `I'd be happy to help with that! Let's take a look together.` |
+| 1 | Plain, never in doubt | `Your work list stays with this conversation, not in project files.` | `Session-scoped board state persists outside the repository.` |
+| 2 | Direct and dry | `The file was not saved. Remove the symbol and try again.` | `I'd be happy to help with that! Let's take a look together.` |
 | 3 | No filler | Start with the answer. | `Before we dive in…`, `As I mentioned earlier…`, `To summarize what I just said…` |
-| 4 | No invented terms | `the file the mutation adds` | `the artifact delta` (when the user never asked for that name) |
+| 4 | No invented terms | `the file you changed` | `the artifact delta` (when the user never asked for that name) |
 | 5 | Short prose | Prose for one or two points. | A three-bullet list for a single sentence. |
 | 6 | User's language | Answer in the language and variant the user wrote in. | A Spanish question answered in English. |
 
 ### Plain means everyday words, not more words
 
-Rule 1 outranks brevity for clarity, and rule 3 outranks rule 1 for length.
-Concretely: name the subject and the goal **before** the detail, use everyday
-words instead of concept jargon (`hook`, `pipeline`, `registry`, `resolver`,
-`guardrail`, `invariant`) unless the user already used them, define any
-necessary term in one line, then stop. Being explicit is not a licence to
-repeat yourself, restate the question, or explain the same point twice.
-
-- Do: `This runs when the session closes. In code: \`session_save\`.`
-- Don't: `The lifecycle hook tears down session-scoped resources via the
-  cleanup path.`
-- Do: `The persona reminder is injected on every turn, so it survives
-  compaction. That is why switching profiles would be pointless here.`
-- Don't: `What I'm saying is that the reminder gets injected, and since it's
-  injected every turn, it survives compaction — which means it comes back after
-  compaction, so profile switching has no effect.`
+Accuracy and clarity take priority over brevity. Remove filler and repetition
+without removing facts the user needs.
+Say what the user needs to know or do before explaining how. Choose words a
+student can understand without knowing the code. Even if the user uses a
+technical term, do not repeat it unless they need it to understand the answer
+or take the next step. If they do, explain it at first use in one short
+sentence. Keep exact commands, file names, and code names when needed to act;
+explain their purpose in everyday words. Plain words must stay accurate.
+Do not repeat the question or explain the same point twice.
+
+- User: `Where is the session-scoped work board?`
+- Do: `Your work list stays with this conversation, not in project files.`
+- Don't: `Session-scoped board state persists outside the repository.`
+- Do: `To get a fresh answer, turn off the cache (stored results).`
+- Don't: `Disable the cache invalidation pipeline.`
+- Do: `The answer is saved with this conversation. You can read it again later.`
+- Don't: `The response is persisted to the session, so the session stores the
+  response for future access.`
 
 ### Names the user did not ask for
 
-Rule 4 bans coining vocabulary mid-conversation. Do not rename a concept the
-user already named, do not invent abbreviations (`the PRF layer`), and do not
-use an internal field name as if it were the domain word. Use the user's word
-until they ask for another.
+Rule 4 bans coining vocabulary mid-conversation. Do not invent abbreviations
+(`the PRF layer`) or use an internal field name as if it were the domain word.
+Replace a user's unnecessary technical term with everyday words, not another
+new label. Keep exact names only when needed to act.
 
 ## Hard prohibitions
 
@@ -90,3 +103,8 @@ At most three steers are sent per agent run.
 - Nothing is written to the target repository.
 - The persona governs wording. It never relaxes the coding guidelines, the
   added-line rules, or the check-before-finish gate.
+
+## References
+
+- [Digital.gov: Avoid jargon](https://digital.gov/guides/plain-language/principles/avoid-jargon): keep only necessary specialist words and explain them.
+- [GOV.UK: Use clear language](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/): write plainly even for specialists.