@leing2021/super-pi 0.27.0 → 0.28.0

package/README.md

@@ -114,7 +114,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 | [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, and the idea that agents need hard gates instead of gentle suggestions. |
 | [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | The five-step think → plan → build → review → learn loop and the knowledge-compounding backbone. |
 | [gstack](https://github.com/garrytan/gstack) | YC-style forcing questions, CEO Review cognitive frameworks, browser QA patterns, failure maps, and evidence-first validation. |
-| [mattpocock/skills](https://github.com/mattpocock/skills) | Context glossary (`CONTEXT.md`) for cross-session term persistence, lightweight ADR with three-condition threshold, feedback-loop-first debug discipline (full diagnosis loop with completion criteria and post-mortem handoff), deep-module vocabulary, the review Spec axis (plan-vs-diff with traceback to original wording), and the out-of-scope knowledge base. Adopted as self-contained `skills/references/` — no external path deps, no issue-tracker deps. |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | Context glossary (`CONTEXT.md`), lightweight ADR (three-condition threshold + "What qualifies" catalog), feedback-loop-first debug discipline, deep-module vocabulary (module/interface/depth/seam/adapter/leverage/locality + internal seams + rejected framings), interview discipline (facts-vs-decisions, one-question-at-a-time), the review Spec axis, and the out-of-scope knowledge base. Absorbed as self-contained `skills/references/` content — no external path deps, no issue-tracker deps, no standalone skills grafted (super-pi's existing 01-brainstorm/domain-language/module-design already cover the active disciplines). |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",

package/skills/01-brainstorm/references/premise-challenge.md

@@ -25,4 +25,10 @@ PREMISES:
 3. [statement] — agree/disagree?
 ```
 
-Use `ask_user_question` to confirm each premise. If the user disagrees, revise understanding and loop back.
+Use `ask_user_question` to confirm each premise. **One question at a time** — asking multiple at once is bewildering. If the user disagrees, revise understanding and loop back.
+
+## Interview discipline (from grilling)
+
+- **Distinguish facts from decisions.** If a *fact* can be found by exploring the environment (filesystem, existing code, tools, docs), look it up rather than asking. The *decisions* are the user's — put each one to them and wait.
+- **Walk the decision tree one branch at a time**, resolving dependencies between decisions one by one. For each question, provide your recommended answer so the user can confirm or correct efficiently.
+- **Do not act** until you and the user reach a shared understanding of all premises.

package/skills/references/domain-language.md

@@ -39,6 +39,26 @@ Only when **all three** are true:
 
 If any is missing, skip the ADR. Most decisions don't qualify.
 
+### Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. Numbered: `0001-slug.md`, increment by scanning `docs/adr/`. Optional sections (Status / Considered Options / Consequences) only when they add genuine value.
+
+### What qualifies
+
+- **Architectural shape** — "write model is event-sourced, read model projected into Postgres."
+- **Integration patterns between contexts** — "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in** — database, message bus, auth provider. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions** — "Customer data is owned by the Customer context; others reference it by ID only." Explicit no-s are as valuable as yes-s.
+- **Deliberate deviations from the obvious path** — "manual SQL instead of an ORM because X." Stops the next engineer from "fixing" something deliberate.
+- **Constraints not visible in code** — "can't use AWS because of compliance", "response times must be under 200ms."
+- **Rejected alternatives when non-obvious** — considered GraphQL, picked REST for subtle reasons. Otherwise someone suggests GraphQL again in six months.
+
 ## Consumption rules (every skill)
 
 1. **Before broad project reads**, check if `CONTEXT.md` exists at the repo root (or the relevant context in a multi-context repo). If it exists, read it first so you use the project's vocabulary.

package/skills/references/module-design.md

@@ -46,17 +46,55 @@ A shared vocabulary for designing module shapes. Use these terms wherever code i
 
 ## Principles
 
-- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable parts — they just aren't part of the interface.
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
 - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
 - **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
 
 ## Designing for testability
 
-1. **Accept dependencies, don't create them.** `function processOrder(order, paymentGateway)` is testable; `function processOrder(order)` that news up its own gateway is not.
-2. **Return results, don't produce side effects.** `function calculateDiscount(cart): Discount` is testable; `function applyDiscount(cart): void` that mutates is not.
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
 3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
 
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
 ## Where this is used
 
 - **03-work** — when designing or restructuring a module, use these terms to evaluate depth and seam placement.