@antoneeo/kb-agentic-skill 1.24.0 → 1.26.0

package/skills/kb-agentic-skill/templates.md

@@ -103,18 +103,30 @@ the first draft — the properties that make a rule survive a motivated reader a
 cheap to apply while writing and expensive to retrofit. `vision.md` §6 is the
 blind check that gates promotion to APPROVED.
 
+**No section below is written before the owner interview** (`vision.md` §The owner
+interview) and its approved north star. Until then — at bootstrap, or for an owner
+not yet reached — the file is this stub, and nothing traces to it:
+
+```markdown
+# Project Vision
+Status: DRAFT
+<!-- STUB: awaiting the owner interview (vision.md §The owner interview). Not a
+     Vision: no artifact traces to it. What the agent observed is in strategic/. -->
+```
+
 Sections below marked **[gate]** are load-bearing for that ruling; the others are
 orientation for humans. Keep the human ones — just know which is which.
 
 ```markdown
 # Project Vision
 Status: DRAFT
-<!-- Status: DRAFT (reconstructed by the agent, NOT a gating authority)
+<!-- Status: DRAFT (written from the owner interview, NOT yet a gating authority)
      or APPROVED (by <who>, <date>) — only after the user's explicit confirmation
      AND the blind check in vision.md §6. -->
 
 ## North Star
-<!-- [gate, partly] The BENEFIT to be obtained — what the actor gets, never the
+<!-- [gate, partly] One or two sentences IN THE OWNER'S WORDS, approved before any
+     other section (Gate 1): (approved: REQUEST_[topic].md#R<n>). The BENEFIT to be obtained — what the actor gets, never the
      mechanism, and never by comparison to another product (a comparative
      definition rots silently when the comparison target moves). Concrete enough
      that an obstacle to it is recognizable: that is what makes every Non-Goal
@@ -123,11 +135,15 @@ Status: DRAFT
      scale levels. Routing the reader to another file breaks the cold-read
      premise. -->
 ## Core Problem
-<!-- Human orientation: what goes wrong without this product. Carries no gate
-     weight unless the admission test names it. -->
+<!-- Interview question 1: ONE concrete case that today does not get the expected
+     result, with its example — never a missing feature. Cite the answer
+     (REQUEST_[topic].md#R<n>). Human orientation: carries no gate weight unless
+     the admission test names it. -->
 ## Actors
 <!-- [gate] the cast this product serves. One light line per actor:
      **Role** — primary goal; good UX = what a good experience means to them.
+     Interview question 3: who receives the benefit, who acts, and who has the
+     INITIATIVE — an actor that acts unprompted is named here, or it goes missing.
      The "good UX =" clauses are admissible work, not decoration — say so in the
      admission test. Define each actor ONCE here; use-cases (Standalone) / D-UC
      (Hybrid) reference them by role and never re-describe them (anti-DRY).
@@ -144,7 +160,14 @@ Status: DRAFT
      with BOTH branches answered, plus an anti-laundering clause naming the
      re-descriptions you expect. Omit the section if the product has none. -->
 ## Non-Goals
-<!-- [gate — the REJECT side; this is your ENTIRE rejection surface]
+<!-- [gate — the REJECT side, with the Invariants]
+     A Non-Goal bounds SCOPE: it rejects a proposal that pursues what it names; it
+     never bans a behaviour the product already has and never creates an
+     obligation (obligations come from the North Star and the Success Signals). A
+     behaviour that must never happen is an Invariant, with its provenance.
+     PROVENANCE on every rule, at the end of its bullet: (source: owner
+     REQUEST_[topic].md#R<n> | higher Vision: "quoted line" | inference confirmed
+     REQUEST_[topic].md#R<n>). An unconfirmed author inference is not a rule.
      Derive every rule by the deletion test: remove it — if the benefit is still
      reachable, the rule does not belong (it spends a degree of freedom on
      nothing); if not, keep it and name the obstacle it removes. Constraints
@@ -164,7 +187,7 @@ Status: DRAFT
      clause. State the default for anything unreached, per path. -->
 ## Success Signals
 <!-- [gate] Each checkable against a NAMED artifact or command by someone who was
-     not here. Not "we are the best" — a file, a command, a battery, and what the
+     not here, with its STARTING VALUE (interview question 4). Not "we are the best" — a file, a command, a battery, and what the
      result must be. -->
 ## Where the rest lives
 <!-- Pointers, so an absence reads as intentional rather than as a gap. Competitive
@@ -197,16 +220,32 @@ Only for features spanning multiple ANALYSIS documents or multiple milestones: o
 ```markdown
 # Feature Vision: [Name]
 
+<!-- Written only after the owner interview (vision.md §The owner interview). Each
+     section cites the answer it comes from: REQUEST_[topic].md#R<n>. -->
+## North Star
+<!-- One or two sentences in the owner's words, explicitly approved before any
+     other section (Gate 1): (approved: REQUEST_[topic].md#R<n>). -->
 ## Problem
+<!-- One concrete case that today does not get the expected result, with its
+     example — not a missing feature. -->
 ## Expected Benefit
+<!-- What who obtains once solved: a result, not a function. -->
 ## Actors
 <!-- the cast this feature serves — usually a subset/refinement of the project
      Actors, or a distinct feature-local cast for internal-tooling work. One light
      line each: **Role** — primary goal; good UX = what good feels like.
+     Name who receives the benefit, who acts, and who has the initiative.
      Referenced by the use-cases, not re-described in them. -->
 ## Success Signals
+<!-- Observable, each with its starting value. -->
 ## Non-Goals / Out of Scope
+<!-- Scope this feature does not pursue. Not a ban on existing behaviour, and no
+     obligation: those come from the Benefit and the Signals. -->
 ## Related Constraints and Principles
+<!-- Each with its provenance: (source: owner REQUEST_[topic].md#R<n> | higher
+     Vision: "quoted line" | inference confirmed REQUEST_[topic].md#R<n>). A
+     constraint imported from a higher Vision is asked about, never assumed to
+     apply here. -->
 ```
 
 ## ai_docs/audit/requests/REQUEST_[topic].md

package/skills/kb-agentic-skill/vision.md

@@ -47,14 +47,67 @@ Four consequences, each operational:
 
 Extracting the benefit from a discussion is real work: a discourse arrives with
 solutions, preferences and constraints tangled together, and the Vision is the
-distilled benefit only. The elicitation round (`elicitation.md`) asks for it first
-— and a mechanism ("a dashboard") is not an acceptable answer to a benefit
-question ("never lose the thread"); ask again until the answer names what the
-actor obtains.
+distilled benefit only. The owner interview below asks for it — and a mechanism
+("a dashboard") is not an acceptable answer to a benefit question ("never lose
+the thread"); ask again until the answer names what the actor obtains.
 
 The deletion test decides **which** rules exist. Everything below decides **how**
 to write a rule so it holds once you know it must exist.
 
+## The owner interview (before any Vision text)
+
+A Vision is the **owner's** statement of what is to be obtained. Nothing in this
+file after this section can detect a Vision the author wrote alone: the blind
+check (§6) tests whether the rules survive a hostile reader, never whether they
+are the owner's. So every Vision is born from an interview of the owner, and its
+north star is approved **before** a line of it is drafted.
+
+**Scope — every Vision, in every mode:** `project_vision.md`, a feature
+`VISION_*.md`, a lens Vision (course, marketing), and the devPNT M-VISION in
+Hybrid; also an ANALYSIS `## Feature Vision` that states a benefit no existing
+Vision names (one that cites an approved Vision's benefit is alignment, not a
+Vision). An amendment re-runs the questions whose answers it changes, and Gate 1
+again when the north star changes. **There is no skip path**: one sentence from
+the user plus a spike is not a complete spec — that exact shortcut produced a
+Vision with an imported prohibition, no north star and a missing actor, and four
+downstream artifacts built on it (field case, 2026-10). A reply already on record
+in the owner's words is read back for confirmation, never re-asked as an open
+question; an answer the author derived (from a spike, the code, another Vision)
+is never an answer — it is a proposal the owner confirms or rejects.
+
+**The questions, in this order.** Each is repeated until its answer has the form
+stated; the wrong form is named so it can be recognized and asked again.
+
+| # | Question | Right form | Wrong form — ask again |
+|---|---|---|---|
+| 1 | **Problem** — which concrete case today does not get the expected result? | one real case, with an example | a missing feature ("there is no drawing tool") |
+| 2 | **Benefit** — once solved, who obtains what? | a result for a named actor | a function or mechanism ("a renderer") |
+| 3 | **Actors** — who receives the benefit, who acts, who has the initiative? | all three named, initiative included | only the one who asks — the actor who acts unprompted goes missing |
+| 4 | **Success** — what observable signal shows the benefit arrived? | a signal with its starting value | a feeling, or a signal with no baseline |
+| 5 | **Boundaries** — what does this NOT pursue? | scope excluded from this work | a ban on behaviour ("X must never happen") — that is a constraint (6) or an obligation (2, 4) |
+| 6 | **Known constraints** — each with its provenance: owner, a quoted line of a higher Vision, or author inference | every constraint sourced; every inference asked here | a constraint written in silently, or imported from a higher Vision without asking whether it applies here |
+
+A **Non-Goal bounds scope**: it rejects a proposal that pursues what it names; it
+is not a ban on behaviour that already exists, and it creates no obligation.
+Obligations come from the Benefit and the Success Signals.
+
+**Gate 1 — north star.** One or two sentences, in the owner's words, explicitly
+approved by the owner. The author may compose a wording from the answers; the
+approval is of that exact text, recorded verbatim in the request record
+(`audit/requests/REQUEST_[unit].md`; a Vision written outside any unit, such as
+the project Vision after bootstrap, records its interview in
+`audit/requests/REQUEST_project_vision.md`). **Without it no Vision text is written** —
+not a DRAFT, not a reconstruction: bootstrap writes a stub awaiting the
+interview, and what the agent observed goes to `strategic/`.
+Unattended, the unit is `BLOCKED on the user` (`elicitation.md` Unattended path).
+
+**Gate 2 — the full Vision**, written from the answers. Every section traces to
+an answer or a stated provenance (`REQUEST_[unit].md#R<n>`); every rule carries
+its provenance; an author inference the owner did not confirm is not in it. The
+blind check (§6) verifies that it holds; the approved north star verifies that it
+is the owner's. Promotion to APPROVED still needs the owner's explicit
+confirmation — Gate 2 is that confirmation, given on the written text.
+
 ## 0. The one-line test
 
 > Could a reader who has never seen this project rule ACCEPT or REJECT on a
@@ -138,7 +191,14 @@ rule that survived and the same rule leaking.
 This is the most common structural failure and it is invisible from the inside.
 
 - **A Goal cannot reject anything.** If the admission test says "advances a Goal
-  and violates no Non-Goal", then rejection power lives *only* in the Non-Goals.
+  and violates no Non-Goal", then rejection power lives *only* in the Non-Goals
+  (and the Invariants, where the Vision has them).
+- **A Non-Goal rejects scope, not behaviour.** It turns away a proposal that
+  pursues what it names; it never forbids a behaviour the product already has, and
+  it never creates an obligation — obligations come from the Benefit and the
+  Success Signals. A behaviour the product must never have is an Invariant, or a
+  constraint with its provenance (§The owner interview, question 6). Written as a
+  Non-Goal, it reads as a ban the owner never stated.
   A Goal that says "scale cost to risk in both directions" cannot stop cost
   inflation — you need a prohibition for that.
 - **A prohibition scoped to one rung of your own scale protects only that rung.**
@@ -204,7 +264,10 @@ it.
 ## 6. The blind check (procedure)
 
 Run this **before promoting any Vision to APPROVED, and before any amendment of an
-approved one**. Not for DRAFT edits — promotion is when authority is granted, and
+approved one**. It runs on a Vision that already passed Gate 1 (§The owner
+interview): it tests whether the rules hold against a hostile reader, and it
+cannot see whether they are the owner's — a Vision the author wrote alone passes
+it cleanly. Not for DRAFT edits — promotion is when authority is granted, and
 it is rare, so the cost lands where it buys most.
 
 1. **Give the reviewer the document text and nothing else.** Not a path — the