@antoneeo/mkt-agentic-sdlc-skill 0.2.1 → 0.3.1

package/skills/mkt-agentic-sdlc/review.md

@@ -1,73 +1,180 @@
-# CMO Review Discipline
-
-Applies at the Strategy gate (phase 6), the final packaging gate (phase 9),
-and any independent review slot in a connected governance layer (devPNT
-review gates). This is the single definition of how to request, receive, and
-perform a marketing review; other places point here instead of restating it.
-
-The reviewer is a skeptical CMO with a fresh context: different session or
-subagent, read-only, given the artifacts — never "review my session".
-Fallback when no independent context is available: run the battery yourself
-as an explicit, separate adversarial pass, and say so (independence is
-reduced).
-
-## Requesting
-
-Hand the reviewer:
-- **Scope**: which artifact, which gate, in one or two lines.
-- **The artifact itself** — full text, not a paraphrase.
-- **The constraints it derives from**: the approved MKT-VISION, the
-  OBJECTIVES (for strategy/tactics reviews), the ICP_PERSONAS and THREAT_MAP,
-  and the **evidence ledger** — the reviewer checks the artifact **against**
-  them, not only for internal consistency.
-- Which finding classes to cover when the default is not obvious.
-
-## Receiving
-
-**Answer findings one by one — fix, or justify with evidence.** Silent drops
-turn review into theater. Disagree explicitly with reasoning; never resolve a
-disagreement by rewording the finding. Cap 3 rounds; then surface open
-findings to the user rather than looping. If any edit is made after a PASS,
-re-review: reviewed text must equal shipped text.
-
-## Reviewing — the red-flag battery
-
-Severity: `BLOCK` (artifact does not pass the gate) / `WARN` (ships only with
-explicit user acknowledgment). Every finding cites its location.
-
-| # | Check | Severity |
-|---|---|---|
-| R1 | **Swap test**: replace our name with the top competitor in the positioning STATEMENT ACTUALLY PUBLISHED (not a stronger paraphrase — test the exact sentence that ships); if it still holds for any competitor, positioning does not exclude | BLOCK |
-| R2 | **Untraced number**: any figure without `[EV-nn]` | BLOCK |
-| R3 | **Laundered assumption**: ASSUMPTION used as certainty in prose ("the market is worth X" vs "we assume X-Y") | BLOCK |
-| R4 | **Orphan tactic**: tactic serving no objective; **orphan objective**: objective with no KPI or no serving tactic | BLOCK |
-| R5 | **Broken funnel math**: chain does not recompute, or projected outcome does not meet the objective target and no gap is declared | BLOCK |
-| R6 | **Missing kill/scale criteria** on any funded channel | BLOCK |
-| R7 | **Stale benchmark**: >24 months old, not flagged | WARN |
-| R8 | **Top-down-only TAM**: no bottom-up cross-check | WARN |
-| R9 | **Invented persona**: persona trait with no VoC trace and no ASSUMPTION label | WARN |
-| R10 | **Channel vs ICP mismatch**: channel scores poorly on the selection matrix with no written rationale | WARN |
-| R11 | **Generic messaging**: pillar without proof points; value prop interchangeable with any competitor's | WARN |
-| R11b | **Low-cost trap / price-led positioning**: the positioning leads with cheapness ("prezzo onesto", "senza pagarlo caro", price comparison as the hook) instead of leading with value and framing price as a consequence — invites the customer to leave for the next cheaper option | WARN (BLOCK if the whole prop reduces to price) |
-| R12 | **Vision divergence**: artifact pursues a goal absent from the approved MKT-VISION, or violates a non-goal | BLOCK |
-| R13 | **Capacity fiction**: plan requires execution capacity Wave 3 says does not exist | BLOCK |
-| R14 | **SMART violation**: objective without number, date, or owner | WARN |
-| R15 | **Strawman swap-test**: the swap-test verdict tests a differentiated formulation while a WEAKER, generic sentence is what actually ships as the positioning line | BLOCK |
-
-## Conformance statement (strategy & final-plan reviews)
-
-A PASS is **not valid on "found nothing"**. The verdict must map each
-constraint to evidence: every approved objective → the strategy element
-serving it → the tactics funding it → the KPI measuring it (cite sections);
-every MKT-VISION benefit and non-goal → where the artifact honors it; every
-material ledger ASSUMPTION → where the plan declares it. A gap in the chain
-is a finding, not a footnote. Quick E1/E2 reviews stay findings-only.
-
-## Anti-patterns
-
-- **Praise padding** — a review reports problems and fixes.
-- **Batch-dismissal** of a findings list with one blanket reply.
-- **Severity inflation/deflation** — a style preference is not a BLOCK; a
-  broken funnel is not a nit.
-- **Scope-creep findings** — issues outside the artifact under review are
-  filed separately, not mixed in.
+# Review Discipline
+
+The single definition of how to request, receive, and perform a review. Other
+places that need review behavior point here instead of restating it (DRY) —
+including devPNT's §4.5/§4.6 gates and any future review step.
+
+## When a review is due
+
+Two moments, and they review different things:
+
+| # | Moment | Object | Level |
+|---|---|---|---|
+| **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
+| **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+
+**Why the design review is its own moment, and not a nicety.** The closure review
+can only tell you the code matches the design; it cannot tell you the design was
+wrong. An omission in the design — an impacted file nobody listed, a threat with no
+answering requirement, a capability ruled EXISTS on an assumption — is *cheapest*
+to fix before code exists and most expensive after. And the author cannot catch it:
+a self-review runs in the context that produced the omission and is structurally
+blind to it, which is why independence, not effort, is what this gate buys.
+
+**Independence, best realization the client supports** — declare which one you used:
+
+1. **A fresh subagent** (Claude Code's Task tool, or the equivalent facility) with
+   its own context, given the artifacts below and nothing from this conversation.
+2. **A one-shot run of the client itself** (`gemini -p "…"`, `codex exec "…"`) with
+   a SELF-CONTAINED prompt — the reviewer session has no other context, which is
+   exactly what makes it independent.
+3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
+   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
+   exists**: on a client with a subagent facility or a one-shot CLI, descending to
+   it is choosing zero independence, which is the one thing this gate buys. When
+   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
+   facility on this client)` — not merely that you did. A rung named without its
+   reason is indistinguishable from a rung chosen for convenience.
+
+Rung 3 stays in the ladder deliberately: it is what keeps the methodology
+completable with no network, no account and no subagent facility. It is a floor,
+never a default.
+
+Use a different model from the author's where the client allows it.
+
+**Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
+after the third, stop and surface them to the user with the artifact — a gate that
+can block forever gets removed. **Log one row per completed review, PASS or FAIL**
+— a FAIL surfaced to the user is the highest-value outcome the gate produces, and
+logging only passes would erase exactly that evidence. The row goes in
+`ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
+`| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
+Hybrid project's devPNT gates write to the same file.
+The log is how the gate's value is measured over time; skipping it makes the gate
+unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
+
+**The reviewer is read-only and advisory.** It never edits, never commits, never
+marks anything DONE, and a PASS is not an approval to merge — the human owns that.
+
+## Requesting
+
+When you hand work to a reviewer (human or agent), give them:
+
+- **Scope**: what changed and why, in one or two lines.
+- **The authoritative design artifact**: the ANALYSIS, E-TDD, or equivalent
+  the change was built against — not a paraphrase of it.
+- **The actual diff**: the real changed files, not a description of them. (For a
+  **design** review there is no diff yet — that is the point; hand the artifact
+  plus the constraints below, and say the object under review is the design.)
+- **For an impact/solution-analysis review, the constraints it derives from**:
+  the **Vision**, including its `## Actors` (Hybrid: the `M-VISION`; Standalone:
+  `project_vision.md`/`roadmap.md` + the ANALYSIS Vision-Alignment), the
+  **use-cases / user-needs** (Hybrid: `D-UC`;
+  Standalone: the ANALYSIS `## Use Cases / User Needs`), and the **threat model**
+  (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`). Hand these
+  *in addition to* the design artifact — the reviewer checks the artifact **against**
+  them, not only for internal consistency.
+- **For a design review, the threat model too** (same sources as above). Why this
+  one and not the whole set: file coverage crosses the impact-analysis→design hop on
+  a mechanical gate (every impacted file needs a design block), so a dropped file is
+  caught; **threats have no such gate** — a threat answered in the impact analysis
+  can silently fail to become a security requirement in the design, and the later
+  code review only verifies the requirements that are there, never the ones that
+  should have been. The design reviewer checks that every threat surface the change
+  touches has a matching security requirement.
+
+**The verdict travels back as the reviewer's own final output** — the text it
+returns when it finishes, nothing else. A reviewer that tries to message the
+requester mid-run depends on a delivery channel it cannot verify (a subagent
+addressed by agent TYPE rather than by session gets no such channel, and the
+attempt fails silently); a requester that waits for such a message stalls
+holding a verdict that already exists. State the return form when you request
+the review, and read the verdict where it actually arrives.
+
+Never ask a reviewer to "review my session" or "review what I just did"
+without the artifacts above — that forces them to reconstruct scope from
+conversation instead of reviewing the change itself. Say which finding
+classes you want covered (correctness, security, conformance to the design,
+test coverage) if the default scope is not obvious.
+
+## Receiving
+
+**MUST answer findings one by one — fix, or justify with evidence; why:
+silent drops turn review into theater** — a review whose findings are not
+tracked to a resolution gives the appearance of quality control without its
+substance.
+
+If you disagree with a finding, say so explicitly with your reasoning; never
+resolve a disagreement by rewording the finding until it goes away. When the
+project keeps a `REVIEW_LOG` (or equivalent), log the outcome of each
+finding there.
+
+## Reviewing
+
+When you are the reviewer:
+
+- Verify claims against the real source, not against the diff's own
+  description of itself.
+- **Your verdict is your final output.** Deliver findings and verdict as the text
+  you return when you finish — never only through a message to the requester, a
+  channel you cannot verify and which fails silently when it is not there
+  (see `## Requesting`).
+- Cite evidence as `file:line` for every finding — a finding without a
+  location is not actionable.
+- Keep severity honest: do not inflate a style preference to a blocker, and
+  do not soften a real correctness or security issue to a nit.
+- No praise padding. A review reports problems and their fixes, not a
+  summary of what looks fine.
+- **Conformance statement (impact/solution-analysis & design reviews only — not a
+  plain code-diff review).** When the artifact under review carries Vision / use-case
+  / threat-model constraints, your output MUST map each constraint to its evidence: for
+  every use-case/user-need (and the Actor it serves — a use-case with no defined Actor,
+  or an Actor UX expectation the solution does not meet, is a finding), every threat, and
+  every applicable Vision benefit/Non-Goal, state WHERE the artifact satisfies it (section
+  or `file:line`) or raise it as a finding. A PASS/approve is **not valid on "found nothing"** — the conformance
+  statement is the proof the check ran; an unfalsifiable "I checked" is the review
+  theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
+  silent-drop rule). Plain code reviews stay findings-only.
+- **Restated facts (cite, never copy).** Every governance slot has ONE owning document
+  per project. A fact restated in the artifact under review when another document owns
+  it is a **finding**: the fix is a citation naming the owner, not a better copy. This
+  binds the conformance statement too — where a constraint is satisfied by another
+  document, name that document as the evidence instead of repeating what it says. Two
+  copies of one fact diverge at the first edit, and the reader then has no way to tell
+  which one is current. The rule bites hardest across domains, where the same slot
+  ("threat model", "vision", "handoff") carries a different meaning under each lens and
+  a copy looks like an independent second source.
+- **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
+  that carries NO Capability Ledger is itself a finding** — the lens's capability
+  pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left
+  no record, and "the artifact does not have one" is what a skipped pass looks like,
+  not a reason to skip the check. (This half is load-bearing in Hybrid, where the
+  validator backstop reads Standalone ANALYSIS files only and this clause is the
+  sole check that the pass ran.) When the ledger is there, map each
+  ledger row to where the design or diff realizes it. Three findings live here and
+  nowhere else (the capability-pass file named above): a capability ruled MISSING but implemented inside
+  the feature's code path, with no component owning it; a component whose contract
+  names the feature (a second consumer would force it open); and a capability ruled
+  MISSING, not built, and absorbed by quietly reshaping the feature — that is a
+  scope change owed to the user, not a design detail. An EXISTS row with no named
+  path or symbol is itself a finding. A capability built in this change and absent
+  from the `## Component Map` (`strategic/architecture.md`, where the lens keeps one) is a finding too — and
+  so is **a component the pass merely DISCOVERED and did not write**, especially
+  when the change marks that area ANALYZED: the area now looks read, the map is
+  still silent, and the next feature may lawfully rule the capability MISSING and
+  build it twice. And a **MISSING row in an area `audit/audit_plan.md` does not
+  mark ANALYZED, with no searches named**, is the finding that matters most on a
+  project the methodology arrived in recently — an unread map reported as an empty
+  one is how a duplicate of the existing codebase gets designed.
+
+## Anti-patterns
+
+- **Batch-dismissal**: closing out a whole findings list with one blanket
+  reply instead of addressing each finding individually.
+- **Rewording instead of addressing**: editing the finding's text to look
+  resolved without changing the code or providing evidence it is a
+  non-issue.
+- **Scope-creep findings**: raising issues unrelated to the change under
+  review instead of filing them separately.

package/skills/mkt-agentic-sdlc/routing.md

@@ -0,0 +1,100 @@
+# Domain Routing — which lens owns this unit of work
+
+The family ships as sibling skills built from one shared core: each lens carries its
+own **fidelity discipline** (what the work must be faithful to) and its own validation
+rules, over **one** `ai_docs/` tree. This file answers one question: *which lens's
+method governs THIS unit of work?* It does not decide where the resulting file is
+stored (step 5), and it never runs before the triage level is known — L1 never
+reaches it.
+
+## 0. Installed-lens detection — run first, fail open
+
+Look in the skills directory this skill was loaded from for sibling lenses of the
+family, identified by the `name:` in their `SKILL.md`:
+
+| Lens | Skill name | Faithful to |
+|---|---|---|
+| code | `agentic-sdlc` | this repository's code |
+| knowledge | `kb-agentic` | documents the user supplied |
+| marketing | `mkt-agentic-sdlc` | market evidence |
+
+- **No sibling installed, or the directory cannot be read** → the router does NOT run.
+  Work under the loaded lens; read no further. This is the normal single-lens case and
+  it costs nothing.
+- **At least one sibling installed** → run the router below, after the level test, on
+  every L2, L3 and Spike.
+
+Fail-open is deliberate: a detection that cannot answer must never block the work. A
+single-lens project that silently gains a router verdict it cannot act on is worse
+than no verdict at all.
+
+## 1. The router
+
+Run the steps in order. Stop at the first one that decides.
+
+1. **Fidelity / purpose.** What must the work be faithful to?
+   - *This repository's code* → provisional **code**; continue to step 2.
+   - *Documents the user supplied* → **knowledge**. Decided.
+   - *Market evidence* → **marketing**. Decided.
+   - *A deliverable whose purpose is market-facing persuasion* (copy, positioning,
+     campaign material) → **marketing regardless of source**. Decided. Without this
+     branch the marketing lens is reachable only when the *source* is market evidence,
+     never when the *purpose* is marketing — and the launch post written from the
+     release notes routes to code.
+
+2. **Deliverable class** — only on the provisional `code` branch. The predicate is on
+   the deliverable, not on its audience:
+   - *Part of this repository's own document set, shipping and maintained with the
+     code* (`ai_docs/`, README, CHANGELOG, comprehension guides, migration notes) →
+     **code**; continue to step 3.
+   - *A standalone knowledge deliverable whose fidelity extends beyond this repo's
+     code* (user documentation for an external audience, a distilled corpus) →
+     **knowledge**. Decided; step 3 is not reached.
+
+3. **Build-consumed override** — only on the provisional `code` branch, never
+   overriding a *marketing* or *supplied-documents* verdict. *Is the deliverable a
+   file the project's build or test toolchain consumes?* Executable or imported
+   source: yes. Committed Markdown: no. A yes confirms **code**.
+
+4. **Split rule.** A request whose work must be faithful to two sources is **two units
+   of work**, split before routing: the distillation (knowledge) and the design that
+   cites it (code) each route alone. The router returns one lens per unit; it never
+   returns two lenses for one unit.
+
+5. **Owning tree.** A straddling artifact keeps its lens for *method* and takes this
+   repository's tree and validator for *storage*. Lens and location are separate
+   answers — a marketing-lens document written in a code repository still lives in
+   that repository's `ai_docs/` and passes that project's validator.
+
+6. **Cross-check.** If the verdict contradicts an installed skill's `description`, the
+   descriptions are wrong: fix them. Never silently override the test with a
+   description.
+
+## 2. Worked verdicts
+
+| Request | 1 | 2 | 3 | Lens |
+|---|---|---|---|---|
+| "write the API reference docs" (hand-written, ships with the repo) | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "write user documentation for our customers' admins" | code | standalone knowledge deliverable → knowledge | n/a (left the code branch at 2) | **knowledge** |
+| "write the API reference docs" (generated — the work edits docstrings in source) | code | repo's own doc set → code | **build-consumed: yes → confirms code** | **code** |
+| "write a comprehension guide for the auth module" | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "turn these vendor specs into a technical design" | split (step 4): spec = supplied docs; design = this repo | — | — | **knowledge** for the distillation; **code** for the design, citing it |
+| "write the pricing page copy from our market research" | **purpose: market-facing → marketing** | never reached | never reached | **marketing**; stored in this repo's tree (step 5) |
+| "write the launch blog post from the release notes" | purpose: market-facing → marketing | never reached | never reached | **marketing** |
+
+## 3. Acting on the verdict
+
+The verdict binds the **method and the validation rules**, not the storage:
+
+- **Verdict = the loaded lens** → continue; nothing changes.
+- **Verdict = a sibling lens** → say so, and work that unit under the sibling's method
+  and its rule set (its templates, its mandatory risk section — code
+  `## Security and Threat Model`, knowledge `## Sources and Verification`, marketing
+  `## Threat Map / Plan Risks`). The artifact is written with an explicit
+  `domain:` field so the answer survives the session, and it stays in this project's
+  `ai_docs/` tree (step 5).
+- **The unit was split** (step 4) → route and declare each half separately.
+
+Documents under `vision/` — the project vision, principles, the roadmap — sit **above**
+the domain split: they belong to no lens and are validated by the core's structural
+rules only. The router is not consulted for them.