@novare-technologies/nvaid 0.0.0-stage → 0.1.0

package/templates/skills/pr-review/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: pr-review
+description: Evaluates an open pull request against this repo's established conventions (branch type, base branch, commit/PR-title format, CI gate status, path and file-shape conventions, PROJECT-RULES.md) and recommends one of three outcomes -- approve and merge, close and delete, or request changes -- with reasoning for each check. Never merges, approves, closes, deletes a branch, or submits a review itself; the human takes the actual action. Use when asked to review a pull request, evaluate a PR, or decide whether to approve, close, or request changes on one.
+invoked_by: On demand, by request -- "review PR #N" or "run the PR Review Skill on PR #N"
+output: a recommendation report to the conversation, plus a suggested review-comment draft. No file written, no GitHub action taken.
+version: 1.0
+---
+
+# PR Review Skill
+
+Reads a pull request against this repo's *current* conventions and recommends one of
+three outcomes. The rules it checks against are never hardcoded here — they live in
+`.claude/skills/github/SKILL.md` and `nvaid/PROJECT-RULES.md`, read fresh every
+time, so this Skill can't drift out of sync with the conventions as they evolve.
+
+**This Skill never takes the action it recommends.** It doesn't call `gh pr merge`,
+`gh pr close`, `gh pr review --approve`, `gh pr review --request-changes`, or delete a
+branch. It reports a recommendation and reasoning; a human reads it and acts.
+
+## Steps
+
+### 1. Gather the facts
+
+```
+gh pr view $ARGUMENTS --json title,body,headRefName,baseRefName,author,state,mergeable,reviewDecision,statusCheckRollup,files
+gh pr diff $ARGUMENTS
+```
+
+Also re-read `.claude/skills/github/SKILL.md` (this repo's copy) and
+`nvaid/PROJECT-RULES.md` before judging anything — the checks below are applied
+against whatever those files currently say, not a memorized version of them.
+
+### 2. Check branch type against actual content
+
+- Does `headRefName` match one of the branch types `github/SKILL.md` currently defines
+  (`feature/<story-id>`, `bugfix/<bug-id>`, `hotfix/<slug>`, `intent/<intent-id>-slug`,
+  or whatever it's since been extended to)?
+- Does the branch **type** actually match what changed? Code changes on an `intent/`
+  branch, or a pure-documentation Elaboration artifact on a `feature/` branch, is a
+  category error. A category error here means the PR is built on the wrong foundation
+  and can't be fixed by pushing more commits to the same branch.
+
+### 3. Check base branch
+
+`develop` in almost every case; `master` only for a declared `hotfix/`. Anything else
+is wrong regardless of how good the content is.
+
+### 4. Check CI status
+
+Every entry in `statusCheckRollup` must be a pass. Any `pending` or `failing` gate means
+this isn't ready for a merge/close/request-changes decision yet at all — say so plainly
+rather than forcing one of the three outcomes prematurely.
+
+### 5. Check commit and PR-title format
+
+Against whatever `github/SKILL.md` currently specifies (Conventional Commits for commit
+messages; the PR title format, once one is defined). Stray artifacts from an unrelated
+project or template — a ticket ID, a company name, placeholder text that was clearly
+never adapted to this project — are a flag here even if the format is otherwise followed
+correctly.
+
+### 6. Check path and file-shape conventions
+
+Compare every changed/added file's path against this repo's established shape
+(`nvaid/intents/INTENT-XXX-slug/`, `.claude/skills/<name>/SKILL.md`, `deploy/`,
+etc. — read from `PROJECT-RULES.md` and the existing repo tree, not assumed). A new
+top-level convention appearing alongside an existing one for the same concept (two
+different intent-tracking shapes, two different daily-report mechanisms) is a
+duplication flag, not something to wave through because each one is internally
+consistent.
+
+### 7. Check for semantic duplication
+
+Does this PR introduce a Skill, file, or concept that already exists under a different
+name? Read the existing `.claude/skills/*/SKILL.md` descriptions and compare — a new
+Skill whose description overlaps meaningfully with an existing one is worth flagging
+even if no path literally collides.
+
+### 8. Check the PR description itself
+
+Per `github/SKILL.md` Step 3: does the body link the relevant design doc / contract and
+name the Acceptance Criteria it closes, where applicable? A PR with no explanation of
+what changed or why is weaker evidence for a decision, not a blocker on its own.
+
+### 9. Synthesize one of three recommendations
+
+- **Approve and merge** — every check above passes; nothing outstanding.
+- **Close and delete** — a foundational defect (wrong branch type/category error, or
+  fully superseded by other already-merged work) that pushing more commits can't fix.
+  The right move is recutting on a corrected branch, not iterating in place.
+- **Request changes** — the branch and approach are sound, but something specific and
+  fixable is wrong (a stray example, a missing description detail, a failing test to
+  correct). Iterating on the *same* branch is the right move here, unlike Close.
+
+Output, in this order:
+
+1. **Recommendation** — one of the three, in bold.
+2. **Brief justification** — one sentence, the single core reason driving the verdict.
+   Not a summary of every check — the one fact that would change the verdict if it
+   weren't true.
+3. **Reasoning per check** (pass / fail / flagged) — the full breakdown backing up the
+   one-line justification, so the human can see exactly what it's based on, not just
+   take the verdict on faith.
+
+### 10. Draft a suggested review comment
+
+Write the comment the human could paste in as-is, or edit — summarizing the finding(s)
+driving the recommendation. Never post it — output it in the conversation only.
+
+## Boundaries
+
+- Never run `gh pr merge`, `gh pr close`, `gh pr review`, or delete a branch. Report
+  and recommend; the human's own review submission and merge/close click is the action.
+- Never treat "CI is green" alone as sufficient for Approve — CI verifies code
+  correctness, not convention compliance, path correctness, or duplication, which are
+  exactly what this Skill exists to catch that CI can't.
+- Never soften a Close-and-delete finding into a Request-changes one to avoid
+  recommending a branch be redone — a category error doesn't get smaller by wishing it
+  were a smaller fix.

package/templates/skills/project-ticketing/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: project-ticketing
+description: Creates and updates Epics, Stories, and Bugs in Jira or GitHub Projects per ISSUE-TRACKER-TEMPLATE.md. Use when asked to run the Project Ticketing Skill, create tickets from a Unit Breakdown, or sync ticket status with Construction progress.
+invoked_by: Mob Elaboration (Ceremony 1), Mob Construction (Ceremony 2)
+output: link — a Jira or GitHub Projects ticket
+---
+
+# Project Ticketing Skill
+
+Creates and updates Epics, Stories, and Bugs per `docs/templates/ISSUE-TRACKER-TEMPLATE.md`
+— so ticket shape never drifts from one Intent to the next.
+
+## Steps
+
+1. On Unit Breakdown (Mob Elaboration Phase 5), create one Story or Bug per Unit,
+   classified per `docs/templates/unit-breakdown-rules.md` §3.
+2. Attach each ticket's Acceptance Criteria verbatim from the Unit's own design doc —
+   never re-worded independently.
+3. As Mob Construction moves a Unit through Design → Building → Gates → Merged, update
+   ticket status to match. The ticket reflects the repo, not the other way round.
+4. Once every Unit under an Epic reaches Merged, roll the Epic to "Intent Complete."
+
+## Boundaries
+
+- Never assign a Story or Epic to a Release Checkpoint — that decision belongs to the
+  Release Plan Skill, made at Release Planning Day, not pre-empted here.

package/templates/skills/quality/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: quality
+description: Drafts the Quality Architecture Contract for an Intent, per quality-architecture-contract-generation-rules.md. Use when asked to run the Quality Skill or draft a Quality contract during Mob Elaboration.
+invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
+output: file — intents/<INTENT-ID>/contracts/quality-architecture-contract.md
+---
+
+# Quality Skill
+
+Drafts the Quality Architecture Contract for an Intent, per
+`docs/templates/quality-architecture-contract-generation-rules.md` — the Required Test
+Coverage table the Unit Test and Integration Test gates run against.
+
+## Steps
+
+1. Build the Required Test Coverage table — one row per scenario, classified Happy
+   Path / Negative Path / Edge Case.
+2. Trace every row to one of the owning Unit's stated Acceptance Criteria, and confirm
+   every Acceptance Criterion has at least one covering row — both directions checked.
+3. State which existing SRS NFRs this Intent's Units are held to, beyond the standing
+   baseline; say "none beyond baseline" explicitly when true.
+4. Log any Known Gap the room consciously accepted, flagged rather than dropped.
+5. Write `intents/<INTENT-ID>/contracts/quality-architecture-contract.md`.
+
+## Boundaries
+
+- Never define Solution-Specific gates (Build, Code Coverage, Code Quality,
+  Reusability, Regression Test, SAST) — those are fixed in `docs/templates/PROJECT-RULES.md`
+  §5.2, not something any Intent's contract opts into or out of.
+- A draft, not a verdict — flag it awaiting the Quality Architect's Sign-Off; never
+  present it as final.

package/templates/skills/r3-analytics/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: r3-analytics
+description: Gathers checkpoint-to-checkpoint performance indicators (lead time, gate pass rate, escaped defects, Known Gaps) for R3's Retrospective step. Use when asked to run the R3 Analytics Skill or prepare Retrospective data after a Release Checkpoint ships.
+invoked_by: R3 (Ceremony 4), triggered by a Release Checkpoint shipping
+output: file — process/retro-<checkpoint>.md
+---
+
+# R3 Analytics Skill
+
+Gathers the checkpoint-to-checkpoint performance indicators the Retrospective step
+looks at, so "what does the data actually say" has an answer ready the moment R3 starts.
+
+## Steps
+
+1. On a Release Checkpoint shipping, pull every Intent it bundled and their Units.
+2. Compute lead time (Intent opened → Shippable), Guardrail Gate pass rate, and any
+   escaped defects logged against this checkpoint's Units.
+3. Roll up every Known Gap logged across this checkpoint's Quality Architecture
+   Contracts — a gap doesn't disappear just because the checkpoint shipped.
+4. Draft `process/retro-<checkpoint>.md` with the above, structured for the room to read
+   before proposing Regenerate edits.
+
+## Boundaries
+
+- Report what happened; propose nothing. Which rule files actually change (Regenerate)
+  is the room's call, never this Skill's.

package/templates/skills/release-plan/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: release-plan
+description: Drafts the Release Planning Day deployment plan — which Intents are Shippable, their cross-Intent dependencies, and each one's Customer Experience targets. Use when asked to run the Release Plan Skill or prepare for Release Planning Day.
+invoked_by: Release Planning Day (Ceremony 3)
+output: file — checkpoints/<checkpoint-name>/plan.md
+---
+
+# Release Plan Skill
+
+Drafts the Release Planning Day deployment plan for the room to review and approve —
+never to finalize alone.
+
+## Steps
+
+1. Pull every Intent currently at "Intent Complete" (every Unit Merged) and propose
+   which ones ship together in this Release Checkpoint.
+2. Surface cross-Intent dependencies — an Intent that reads another's output, a shared
+   schema change.
+3. Flag contradictions between Intents built independently — conflicting API shapes,
+   overlapping ownership.
+4. Draft `checkpoints/<checkpoint-name>/plan.md`, including each Intent's Customer
+   Experience targets.
+
+## Boundaries
+
+- Draft the plan; the room decides. Nothing in `plan.md` is final until Release Planning
+  Day signs off on it.

package/templates/skills/solutions/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: solutions
+description: Drafts the Solutions Architecture Contract for an Intent, per solutions-architecture-contract-generation-rules.md. Use when asked to run the Solutions Skill or draft a Solutions contract during Mob Elaboration.
+invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
+output: file — intents/<INTENT-ID>/contracts/solutions-architecture-contract.md
+---
+
+# Solutions Skill
+
+Drafts the Solutions Architecture Contract for an Intent, per
+`docs/templates/solutions-architecture-contract-generation-rules.md` — the cross-role
+boundary and consistency check every other contract this session has to fit inside.
+
+## Steps
+
+1. Assess whether this Intent introduces a new system container, crosses an SRS System
+   Container boundary, or needs a new ADR — state the answer even when it's "no" on
+   every count.
+2. State explicitly what this Intent is and isn't allowed to touch.
+3. Flag any unsupervised-action surface `docs/templates/PROJECT-RULES.md` §7 doesn't
+   already cover.
+4. Cross-check the other contracts drafted this session for contradictions — the
+   Consistency Gate, recorded in writing.
+5. Write `intents/<INTENT-ID>/contracts/solutions-architecture-contract.md`.
+
+## Boundaries
+
+- A draft, not a verdict — flag it awaiting the Solutions Architect's Sign-Off; never
+  present it as final.

package/templates/skills/unit-breakdown/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: unit-breakdown
+description: Cuts an Intent into Units of Work, each with its own Acceptance Criteria, per unit-breakdown-rules.md. Use when asked to run the Unit Breakdown Skill, break down an Intent into Units, or produce a Unit Breakdown during Mob Elaboration Phase 5.
+invoked_by: Mob Elaboration (Ceremony 1), Phase 5
+output: file — intents/<INTENT-ID>/unit-breakdown.md
+---
+
+# Unit Breakdown Skill
+
+Cuts an Intent into Units of Work small enough to build and approve independently —
+a first-cut proposal the room then critiques, not the decomposition of record.
+
+## Steps
+
+1. Read the Intent file (`intents/<INTENT-ID>/intent.md`) and its stated success
+   criteria.
+2. Propose a decomposition into Units, each with its own Acceptance Criteria narrowed
+   from the Intent's success criteria, per `docs/templates/unit-breakdown-rules.md` §2.
+3. Classify each Unit as a Story or Bug (§3), and size it per the file's decomposition
+   heuristics (§4).
+4. Number Units per §5.
+5. Write `intents/<INTENT-ID>/unit-breakdown.md` — the contract index every
+   Architecture Contract Skill downstream reads from.
+
+## Boundaries
+
+- This is a proposal, not the decomposition of record. Mob Elaboration Phase 3
+  ("Mark it up alone") and Phase 4 ("Negotiate live") are where the room actually owns
+  the cut — flag this file as a draft awaiting that review, never as final.
+- Read `docs/templates/unit-breakdown-rules.md` in full before drafting; don't rely on
+  this summary alone for the numbering and classification rules.