devendra-skill-package 1.0.2

package/.github/skills/test-case-validator/VALIDATION_RULES.md

@@ -0,0 +1,411 @@
+# Validation Rules
+
+Seventeen independently addressable rules. Each is self-contained: purpose,
+what to check, how to report it. New rules are added by appending a new
+numbered section here and registering it in `SKILL.md`'s Execution Steps —
+see `docs/EXTENDING.md`. Do not renumber existing rules when adding a new one;
+append at the end even if it logically belongs earlier, so existing
+citations (`Rule 7`, etc.) in past reports stay valid.
+
+Every rule below is filtered through **Rule 17 (Applicability Resolution)**
+first — read that one before any other, because it changes what "missing"
+means for every rule that follows.
+
+---
+
+## Rule 17 — Applicability Resolution
+
+**Purpose**: Prevent a category that doesn't apply to this project from being
+reported as a gap.
+
+**Run this before Rules 1–16.** **Procedure**: see
+`prompts/00-applicability-resolution.md` for the exact steps and output
+shape (`RESOLVED_PROFILE`, `APPLICABILITY_MAP`) referenced below.
+
+1. Resolve the active project profile (`CONFIGURATION.md` → *Project
+   Profiles*), explicit or auto-detected.
+2. For every category referenced anywhere in Rules 1–16, look it up in the
+   Applicability Matrix (`CONFIGURATION.md`).
+3. Mark each category exactly one of:
+   - **Applicable** — proceed with normal validation.
+   - **N/A** — exclude from coverage-percentage denominators entirely; report
+     as `N/A` with the one-line reason from the matrix (e.g. "N/A — no
+     persistent database in this module's scope").
+4. If a category isn't in the matrix at all (a genuinely novel one), default
+   to **Applicable** and flag it in the report's Recommendations section as
+   "not yet classified in the Applicability Matrix — please confirm and add
+   it" rather than silently guessing.
+
+**Report**: One row per category in the Executive Summary's "Scope" table:
+Category | Applicable? | Reason (if N/A).
+
+---
+
+## Rule 1 — Requirement Traceability
+
+**Purpose**: Every requirement must be provably tested; every test case must
+provably trace to a requirement.
+
+**Validate**:
+- Every Requirement (BRD or combined-spec) has ≥1 mapped test case.
+- Every User Story has ≥1 mapped test case.
+- Every Acceptance Criterion has ≥1 mapped test case.
+- Every Requirement ID referenced anywhere is resolvable (no dangling IDs).
+- No orphan test cases (a test case with no requirement it maps to —
+  distinguish from Rule 16's *gated-wiring* orphans, which do have a mapped
+  requirement but lack integration-level evidence).
+
+**Document Integrity sub-check** (run alongside the above, not instead of
+it): note any of — inconsistent ID scheme, a requirement referenced in one
+document but absent from where it should be defined, a section implied by
+cross-references but missing, contradictory statements about the same
+requirement across documents. Report these as their own finding, tagged
+`Document Integrity`, not folded into a coverage percentage.
+
+**Report** (one row per requirement, per `templates/rtm-row.md`):
+Requirement ID | Requirement | Mapped Test Cases | Coverage | Missing | Status | Observation.
+
+---
+
+## Rule 2 — Frontend Coverage
+
+**Purpose**: Validate UI-facing behavior end to end.
+
+**Validate** (each filtered by Rule 17):; UI Rendering · Navigation · Field
+Validation (Mandatory / Optional / Editable / Read-only / Default Values) ·
+Button Clicks · Dropdown · Checkbox · Radio Button · Date Picker · Search ·
+Sorting · Filtering · Pagination · Upload · Download · Responsive Design ·
+Accessibility · Keyboard Navigation · Loading State · Empty State · Success
+Message · Warning · Error Message · Toast · Popup · Confirmation Dialog ·
+Session Timeout · Browser Compatibility · Theme · Localization.
+
+**Automated-suite note**: when `TEST_CASE_INPUT` is component/screen test
+source (React Testing Library, Vue Test Utils, Playwright, etc.), map these
+categories to their code-level equivalents — e.g. "Loading State" →
+a test asserting a `status === 'loading'` render branch; "Error Message" →
+a test asserting an error/alert role renders with the right copy. See
+`prompts/03-extraction-test-cases.md`.
+
+**Report**: Category | Status (Full / Partial / Missing / N/A) | Evidence.
+
+---
+
+## Rule 3 — Backend Coverage
+
+**Purpose**: Validate server-side / data-layer behavior.
+
+**Validate** (each filtered by Rule 17): API Request shape · API Response
+shape · Headers · Authentication · Authorization · Business Logic ·
+Calculations · Data Validation · Data Integrity · Database Validation · CRUD
+Operations · Duplicate Data handling · Concurrency · Retry · Timeout ·
+Failure handling · Rollback · Logging · Monitoring · Caching · Performance ·
+Audit Trail.
+
+**No-real-backend note**: for a frontend-only module that talks to a mocked
+or not-yet-built API, "Backend Coverage" is reinterpreted as **data-layer
+coverage** — DTO-to-entity mapping, repository logic (cache, retry, dedup),
+and the API-client's own request-construction code. State this
+reinterpretation explicitly in the report rather than marking the whole rule
+`N/A` — the underlying risk (does the client build correct requests and
+handle bad responses?) still exists and should still be assessed.
+
+**Report**: Category | Status | Evidence.
+
+---
+
+## Rule 4 — Requirement Coverage (Test-Type Breadth)
+
+**Purpose**: Confirm each requirement is exercised by more than just its
+happy path.
+
+**Validate, per requirement**: Positive · Negative · Boundary · Validation ·
+Business Rule · Calculation · Workflow · API · Database · Integration ·
+Security · Permission · Role-Based Access · Exception · Error Handling ·
+Regression · Smoke · Sanity.
+
+**Report**: Requirement ID | Test types present | Test types absent | Status.
+
+---
+
+## Rule 5 — Test Case Quality (Structural)
+
+**Purpose**: Confirm each test case is well-formed enough to be trusted and
+maintained.
+
+**Every test case (manual or automated) should resolve to**: Test Case ID ·
+Title · Module · Requirement ID · User Story · BRD Reference · Priority ·
+Severity · Test Type · Preconditions · Test Data · Steps · Expected Result ·
+Automation Candidate · Owner · Tags · Status.
+
+**Automated-suite mapping**: a source test file's `describe`/`it` (or
+equivalent) structure supplies Title, Steps (the test body), and Expected
+Result (the assertions) directly. Requirement/User-Story/BRD Reference come
+from an inline tag in the title (e.g. `it('...(FR-006)', ...)`) when present,
+or from `TRACEABILITY_ENGINE.md`'s fuzzy-mapping fallback when absent — in
+the latter case, mark the mapping `inferred` with a confidence level, never
+`confirmed`. Priority/Severity/Owner/Status/Tags typically don't exist in
+source code and should be reported as `not tracked in this suite` rather
+than `missing` — that's a property of the process, not a defect in any one
+test, and it says something different in a report (see Rule 15's Quality
+Score treatment of this).
+
+**Report**: Test Case ID | Missing/untracked fields | Impact.
+
+---
+
+## Rule 6 — Acceptance Criteria Validation
+
+**Purpose**: Confirm each Acceptance Criterion is tested from more than one
+angle.
+
+**Each Acceptance Criterion should have**: a Positive Scenario · a Negative
+Scenario · a Validation Scenario (if it involves input) · a Boundary
+Scenario (if it involves a limit or threshold) · a Business Rule check (if
+one applies) · an Error Scenario · a Permission Scenario (if role/eligibility
+gated) · an API Validation (if it triggers a network call).
+
+Not every AC needs every scenario type — an AC with no input has no
+Validation Scenario to write. Apply judgment, but state the reasoning: "No
+Boundary Scenario expected — this AC has no numeric/length limit" is a valid
+line in the report; a silent absence is not.
+
+**Report**: AC ID | Scenario types present | Scenario types absent/N/A (with
+reason) | Status.
+
+---
+
+## Rule 7 — Missing Scenario Detection
+
+**Purpose**: Catch the categories of input/condition that are easy to forget
+even when the "main" scenarios are well covered.
+
+**Detect absence of coverage for**: Null · Blank · Whitespace-only · Invalid
+Input · Maximum Length · Minimum Length · Special Characters · Unicode ·
+Duplicate Data · Expired Session · Invalid Token · Unauthorized · Forbidden ·
+Network Failure · Offline · Timeout · Retry · API Failure · Database Failure
+· Concurrent Users · Race Condition · Slow Response · Large Data Volume ·
+File Upload · Large File · Invalid File Type · Malicious/Virus File ·
+Pagination · Sorting · Filtering · Accessibility · Localization · Responsive
+Layout · Cache Staleness · Refresh · Browser Back/Forward · Deep Link ·
+Notification.
+
+Filter every entry through Rule 17 first (e.g. "File Upload" categories are
+`N/A` for a module with no upload feature at all — don't report them as
+missing scenarios; they're inapplicable ones).
+
+**Report**: Category | Applicable? | Present? | Affected Requirement(s) | Note.
+
+---
+
+## Rule 8 — Duplicate Test Case Detection
+
+**Purpose**: Find redundant test cases before they multiply maintenance cost.
+
+**Compare across all test cases**: Objective · Requirement mapped ·
+Steps/body · Expected Result · Test Data.
+
+**Classify each pair found**:
+- **Exact Duplicate** — same requirement, same steps, same expected result.
+  Genuinely redundant; recommend removing one.
+- **Partial Duplicate** — same requirement and steps, different expected
+  result or test data (e.g. two boundary values of the same check). Usually
+  fine — this is normal boundary-testing breadth, not waste.
+- **Near Duplicate** — same objective, different requirement or layer (e.g.
+  a unit test and a component test asserting the same worked example).
+  **This is intentional layered coverage, not a duplicate**, unless the two
+  tests are at the *same* layer. State explicitly which case applies —
+  conflating layered coverage with true duplication is a common false
+  positive; see `docs/FAQ.md`.
+
+**Report**: Pair (Test Case IDs) | Classification | Recommendation.
+
+**Performance note (large suites)**: comparing every test case against every
+other is only tractable because comparisons are scoped *within* each
+requirement's mapped test cases (per the "Compare across all test cases"
+step above, grouped by requirement first) rather than across the whole
+suite — a 2,000-test-case suite with an average of 5 tests per requirement
+is ~400 small comparison groups, not one 2,000-choose-2 comparison. If a
+single requirement has an unusually large mapped-test-case count (a few
+hundred+), sample the largest/most-similar-looking clusters first
+(by title/objective similarity) rather than exhaustively comparing every
+pair in that one group, and state in the report that sampling was used and
+why — never silently truncate without saying so.
+
+---
+
+## Rule 9 — Business Rule Validation
+
+**Purpose**: Confirm every documented business rule is both correctly stated
+and tested.
+
+**Validate**: Eligibility Rules · Calculation Rules (cite the exact formula
+from the source document and the exact assertion in the test) · Workflow
+Rules · Approval Flow · Status Transition Rules · Mandatory Document Rules ·
+Configuration Rules · Role Rules · Permission Rules · Validation Rules ·
+Decision Trees (every branch, not just the ones exercised).
+
+**Report**: Business Rule | Source (document + section/line) | Test Evidence
+| Formula/Logic Match? (Yes/No/Partially, with the discrepancy stated) | Status.
+
+---
+
+## Rule 10 — Risk-Based Coverage
+
+**Purpose**: Ensure test depth is proportional to risk, not just to whether a
+requirement has *a* test.
+
+**Thresholds** (from `RESOLVED_CONFIG.risk_thresholds`, defaults shown):
+
+| Risk Tier | Minimum Test Cases | Typical Signal |
+|---|---|---|
+| High | 5 | money/financial calculations, auth/security, data integrity, irreversible actions |
+| Medium | 3 | core user workflows, state management, cross-feature integration |
+| Low | 1 | cosmetic UI, static/read-only display, well-isolated pure functions with no external risk |
+
+Risk tier is assigned by evidence in the source documents (a requirement
+explicitly flagged security/compliance-relevant, or a calculation involving
+money/legal thresholds, is High by default) — never by guessing; if risk
+tier isn't determinable from the documents, default to Medium and say so.
+
+**Report**: Requirement/Feature | Assigned Risk Tier (+ why) | Test Count |
+Meets Minimum? | Gap (if any).
+
+---
+
+## Rule 11 — Quality Checks (Prose / Hygiene)
+
+**Purpose**: Catch issues that don't show up in coverage percentages but
+still erode trust in the suite.
+
+**Validate**: Naming Convention consistency · Formatting consistency ·
+Grammar/clarity · Duplicate steps within one test case · Missing Expected
+Results · Ambiguous test cases (steps that don't determine a single outcome)
+· Incomplete Preconditions · Incorrect Requirement Mapping (a test case that
+cites a requirement ID it doesn't actually exercise).
+
+**Report**: Issue | Affected Test Case(s) | Recommendation.
+
+---
+
+## Rule 12 — Traceability Matrix Assembly
+
+**Purpose**: Produce the master artifact every other rule's report rows
+ultimately summarize into.
+
+See `TRACEABILITY_ENGINE.md` for the linking algorithm and
+`templates/rtm-row.md` for the row shape. Columns: Requirement ID |
+Requirement | User Story | Acceptance Criteria | Mapped Test Cases | Coverage
+% | Status | Observation.
+
+---
+
+## Rule 13 — Coverage Percentage Calculation
+
+**Purpose**: Turn Rule 1–10's findings into the numbers the Final Summary
+reports.
+
+**Calculate** (formulas in `TRACEABILITY_ENGINE.md` § Coverage Formulas, each
+one excluding `N/A`-marked items from its denominator per Rule 17): Total
+Requirements · Covered Requirements · Missing Requirements · Requirement
+Coverage % · Acceptance Criteria Coverage % · Frontend Coverage % · Backend
+Coverage % · Business Rule Coverage % · Negative Coverage % · Boundary
+Coverage % · Security Coverage % · API Coverage % · Database Coverage % ·
+Automation Coverage %.
+
+---
+
+## Rule 14 — Observation Report
+
+**Purpose**: The report's actionable core — every gap found anywhere above,
+consolidated, deduplicated, and made specific enough to act on.
+
+**Every observation must include**: Severity (High / Medium / Low — see
+`docs/FAQ.md` for the rubric) · Evidence (exact citation) · Affected
+Requirement(s) · Affected Test Case(s) (or "none — orphan gap") · Impact
+(what happens in production if this ships as-is) · Recommendation · a
+**Suggested Test Case** (objective + key input + expected result — not a
+full script; see `SYSTEM_PROMPT.md` Rule 9).
+
+**Sample**:
+
+```
+Missing Requirement Coverage — RQ-15
+
+Severity: High
+
+Evidence: RQ-15 ("system must lock the account after 5 failed login
+attempts") is defined in BRD §4.2 and referenced by User Story US-08 AC-3,
+but no test case in the provided suite references RQ-15 or US-08 AC-3.
+
+Affected Requirement: RQ-15 / US-08 AC-3
+Affected Test Cases: None (orphan requirement)
+
+Impact: Account lockout logic could ship unverified; a regression here is a
+security control failure, not a cosmetic bug.
+
+Recommendation: Add positive (5th failure locks the account), negative
+(4 failures does not lock it), and boundary (exactly 5 vs. 6 attempts)
+scenarios before this ships.
+
+Suggested Test Case: "Given 4 prior failed login attempts, when the 5th
+fails, then the account is locked and a lockout message is shown" —
+Expected Result: account status = locked, login blocked even with correct
+credentials until unlock flow completes.
+```
+
+---
+
+## Rule 15 — Quality Score
+
+`QUALITY_SCORING.md` is the single source of truth for category weights,
+the scoring formula, and the worked example — do not restate the weight
+numbers here, in `SKILL.md`, or in `config/default.config.yaml`'s comments;
+a number copied into a second place is a number that can silently drift
+out of sync with the actual rubric. Weights are configurable in
+`RESOLVED_CONFIG.scoring_weights`; the default set is defined once, in
+`QUALITY_SCORING.md`.
+
+---
+
+## Rule 16 — Gated-Behavior Wiring Validation
+
+**Purpose**: Catch the single most common false sense of coverage in mature,
+well-tested codebases — a conditional/gated behavior's *logic* is unit
+tested, but nothing tests it through its real *consumption point*, so a
+wiring mistake (wrong flag name, forgotten `useEffect` dependency, an
+un-called handler) would pass every existing test.
+
+This rule exists as its own numbered rule rather than living inside Rule 1
+because standard traceability checks (Rule 1) are satisfied the moment *any*
+test cites the requirement — they don't distinguish "the underlying function
+is tested" from "the feature actually turns on when it's supposed to."
+`docs/FAQ.md` has the full rationale and the real-world case that surfaced
+this gap.
+
+**Detect, for every requirement described as conditional** (a feature flag,
+a deep-link/URL-triggered action, a role/eligibility gate, a
+scheduled/cron-triggered job, an event-driven side effect):
+
+1. Is there a test of the underlying logic in isolation? (e.g. a pure
+   function, a reducer, a slice transition, an isolated component with the
+   condition passed as a prop)
+2. Is there a **separate** test that exercises the actual consumption point
+   — the screen/controller/handler that *reads* the real gate (the flag
+   accessor, the route param, the session/role check) and *triggers* the
+   behavior — with the gate set to both its true and false state?
+
+If (1) is yes and (2) is no: report a **Gated-Wiring Gap** — logic is
+covered, integration is not.
+If neither exists: this is an ordinary Rule 1 traceability gap, not a
+wiring gap — don't double-count it under both rules.
+
+**Report**: Requirement ID | Gate Condition | Logic-Level Test | Integration-
+Level Test (or "none") | Status (`Full` / `Wiring Gap` / `Untested`).
+
+---
+
+## Applicability Matrix Pointer
+
+Rule 17 depends on a concrete table of category → project-profile
+applicability. That table lives in `CONFIGURATION.md` (not duplicated here)
+so it can be edited independently of the rules that consume it.

package/.github/skills/test-case-validator/config/default.config.yaml

@@ -0,0 +1,62 @@
+skill:
+  name: test-case-validator
+  version: 2.1.0
+
+inputs:
+  combined_spec_mode: auto
+  supported_document_formats: [markdown, pdf, docx, xlsx, csv, txt]
+  supported_test_case_formats: [manual_spreadsheet, gherkin, automated_source]
+
+project_profile:
+  active: auto
+  auto_detect:                # only consulted when active == "auto"
+    order:
+      - match: "TEST_CASE_INPUT matches a source-code glob (*.test.*, *.spec.*, *Test.*, *_test.*)"
+        profile_if_ui_imports_detected: frontend_automated
+        profile_if_no_ui_imports: api_only
+      - match: "TEST_CASE_INPUT is spreadsheet/CSV/Gherkin"
+        profile: manual_qa
+    fallback_profile: default   # used when no rule in `order` matches
+
+profiles:
+  default:
+    description: "No categories excluded — full Rule 2-11 checklist applies."
+    disabled_categories: []
+  frontend_automated:
+    description: "A frontend module with no owned database or backend deploy, tested via component/unit test source files."
+    disabled_categories: [database, browser_compatibility, localization, file_upload_virus_scan]
+    test_case_source: automated_source
+  manual_qa:
+    description: "Traditional manually-authored QA test case suite (spreadsheet/Gherkin), full-stack scope assumed unless stated otherwise."
+    disabled_categories: []
+    test_case_source: manual_spreadsheet
+  api_only:
+    description: "A backend service or API with no owned UI."
+    disabled_categories: [frontend_ui, accessibility, browser_compatibility, localization, theme, keyboard_navigation]
+    test_case_source: automated_source
+  full_stack:
+    description: "Owns both UI and backend/database — every category applies."
+    disabled_categories: []
+
+risk_thresholds:
+  high: 5
+  medium: 3
+  low: 1
+
+scoring_weights:
+  requirement_traceability: 25
+  coverage: 20
+  acceptance_criteria: 15
+  frontend_coverage: 10
+  backend_coverage: 10
+  business_rules: 10
+  quality: 5
+  duplicates: 5
+
+thresholds:
+  pass: 95
+  needs_improvement: 70
+
+rules_enabled:
+  gated_behavior_wiring: true
+  document_integrity_check: true

package/.github/skills/test-case-validator/docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# Architecture
+
+How the modules in this skill fit together. Read this before `EXTENDING.md`
+if you're not already familiar with the file layout.
+
+## Pipeline Shape
+
+```
+(profile/applicability resolved first — prompts/00 ──▶ RESOLVED_PROFILE + APPLICABILITY_MAP)
+
+Inputs                Extraction              Linking             Analysis                Assembly
+──────                ──────────              ───────             ────────                ────────
+USER_STORY_INPUT ──▶ prompts/01 ──▶ US_MODEL ─┐
+                                                ├─▶ prompts/04 ──▶ RTM ──▶ prompts/05 ──▶ coverage tables ─┐
+BRD_INPUT (opt.) ──▶ prompts/02 ──▶ BRD_MODEL ─┘   (TRACEABILITY_ENGINE)         │                         │
+                                                                                  ├─▶ prompts/06 (missing) ─┤
+TEST_CASE_INPUT ───▶ prompts/03 ──▶ TEST_CASE_MODEL ─────────────────────────────┼─▶ prompts/07 (dupes)   ─┼─▶ prompts/10 ──▶ Observations
+                                                                                  ├─▶ prompts/08 (risk)    ─┤        │
+                                                                                  └─▶ prompts/09 (wiring)  ─┘        ▼
+                                                                                                          QUALITY_SCORING.md
+                                                                                                                     │
+                                                                                                                     ▼
+                                                                                                    prompts/11 ──▶ REPORT_TEMPLATE.md ──▶ Final Report
+```
+
+`config/default.config.yaml` (surfaced as `RESOLVED_CONFIG` after Step 1 of
+`SKILL.md`) is read by nearly every box in this diagram — it isn't drawn as
+its own pipeline stage because it's cross-cutting, not sequential.
+
+## Why It's Split This Way
+
+- **Extraction is separated from linking** because the three input types
+  (User Story, BRD, Test Cases) have almost nothing in common in *how* you
+  read them, but produce a common shape (`TRACEABILITY_ENGINE.md` §1) that
+  the linking step can treat uniformly. Adding a fourth input type (say, a
+  Figma-exported design-requirements doc) means adding `prompts/0X` and a
+  mapping into the same canonical model — it does not touch linking,
+  coverage, or reporting at all.
+- **Linking is separated from analysis** because the RTM is consumed by
+  *every* analysis rule (Rules 1-16), not just one. Rebuilding it inside
+  each rule would both duplicate work and risk the rules disagreeing about
+  what's linked to what.
+- **Configuration is data, not logic**, so that changing a threshold, a
+  weight, or which categories apply to a given project type never requires
+  touching `VALIDATION_RULES.md`, `prompts/`, or `TRACEABILITY_ENGINE.md` —
+  see `CONFIGURATION.md`.
+- **Rule 16 (Gated-Behavior Wiring) is a sibling to Rule 1, not a sub-step of
+  it**, because it asks a genuinely different question (does the
+  *integration point* work, not just does *a* test exist) and needs its own
+  report section so the finding is visible rather than hidden inside a
+  technically-passing Rule 1 row. See `FAQ.md` for the concrete case that
+  motivated this.
+
+## File Responsibilities at a Glance
+
+| File/Directory | Answers |
+|---|---|
+| `SKILL.md` | When do I run, and in what order? |
+| `SYSTEM_PROMPT.md` | How should I behave throughout? |
+| `prompts/*.md` | How do I do *this specific step*? |
+| `VALIDATION_RULES.md` | What am I checking, rule by rule? |
+| `TRACEABILITY_ENGINE.md` | How do I decide two things are linked, and how do I turn links into percentages? |
+| `CONFIGURATION.md` + `config/*.yaml` | What varies by project, and what are today's actual values? |
+| `REPORT_TEMPLATE.md` + `templates/*.md` | What does the output look like? |
+| `QUALITY_SCORING.md` | How do I turn findings into one number? |
+| `examples/*` | What does a correct run actually look like end to end? |

package/.github/skills/test-case-validator/docs/EXTENDING.md

@@ -0,0 +1,85 @@
+# Extending This Skill
+
+The whole point of the modular structure (`ARCHITECTURE.md`) is that these
+are additions, not rewrites. If you find yourself editing more than one of
+the "core" files (`SKILL.md`, `SYSTEM_PROMPT.md`, `TRACEABILITY_ENGINE.md`)
+to make a change, stop and reconsider whether the change actually belongs in
+a new `prompts/` file, a new row in `CONFIGURATION.md`'s Applicability
+Matrix, or a new rule in `VALIDATION_RULES.md` instead.
+
+## Add a New Validation Rule
+
+1. Append a new numbered section to `VALIDATION_RULES.md` (do not renumber
+   existing rules — old report citations like "Rule 7" must stay valid).
+   State its Purpose, what to Validate, and its Report shape, matching the
+   style of Rules 1-16.
+2. Add a corresponding `prompts/NN-your-rule-name.md` file describing the
+   step-by-step procedure, following the shape of
+   `prompts/09-gated-wiring-validation.md` (the most recently added rule) as
+   a template.
+3. Register the new step in `SKILL.md`'s Execution Steps list, in the
+   correct pipeline position (does it need the RTM first? Does anything
+   downstream need its output?).
+4. Add a new numbered section to `REPORT_TEMPLATE.md` if the rule produces
+   its own report section (like Rule 16 did), or fold its output into an
+   existing section if it's a refinement of an existing check.
+5. Add the new category's weight to `QUALITY_SCORING.md` and
+   `config/default.config.yaml`'s `scoring_weights` — **and rebalance the
+   others so the total still sums to 100.**
+6. Add a worked instance to one of the `examples/` reports, or create a
+   third example if neither existing one naturally exercises it — an
+   unexercised rule is a rule nobody has verified actually produces a
+   sensible finding.
+7. Add a `CHANGELOG.md` entry.
+
+## Add a New Project Profile
+
+1. Add the profile to `CONFIGURATION.md` and `config/default.config.yaml`'s
+   `profiles` map: a description, `disabled_categories`, and (if relevant)
+   a `test_case_source` default.
+2. Add a row for the new profile to the Applicability Matrix table in
+   `CONFIGURATION.md` for every existing category — don't leave cells
+   implicitly blank; every category needs an explicit Applicable/N/A
+   determination for every profile, or Rule 17 step 4's "not yet
+   classified" fallback will fire constantly for that profile.
+3. Add or extend an `auto_detect.order` entry (or `auto_detect.fallback_profile`
+   if it should be the new catch-all) if the profile should be reachable via
+   auto-detection, not just explicit selection.
+4. Consider whether an example under `examples/` should demonstrate it.
+
+## Add Support for a New Input Format
+
+1. If it's a new *document* format (User Story/BRD) that isn't already
+   covered by "Markdown, PDF, DOCX, XLSX, CSV, TXT" — this is usually just a
+   parsing detail, not a new extraction procedure; note it in
+   `SKILL.md`'s Inputs table and `prompts/01`/`02`'s Step 0.
+2. If it's a new *test case* format (e.g. a new test framework's block
+   syntax for automated source, or a new manual-test tool's export format)
+   — extend `prompts/03-extraction-test-cases.md` §B's language/framework
+   list, following the same "named, nested grouping of individually-titled
+   assertions" pattern already documented there.
+
+## Add a New Report Section
+
+Only do this if the section reports something genuinely new — if it's a
+different view of data already in another section (e.g. "show me just the
+High-severity items"), that's a filter a report *consumer* can apply, not a
+reason to add Section 21. Sections should map 1:1 to a rule or a rule
+family, matching the existing Rule → Section correspondence in
+`REPORT_TEMPLATE.md`.
+
+## Things to Never Do When Extending
+
+- Never hardcode a threshold, weight, or category list directly into
+  `VALIDATION_RULES.md` or a `prompts/*.md` file if it's the kind of value
+  that should vary by project — put it in `config/default.config.yaml` and
+  reference it as `RESOLVED_CONFIG.<field>`.
+- Never remove a rule or renumber an existing one to "clean up" the
+  numbering — old reports and citations depend on rule numbers staying
+  stable. Deprecate instead: mark it deprecated in `VALIDATION_RULES.md`
+  with a pointer to its replacement, and note the deprecation in
+  `CHANGELOG.md`.
+- Never change `SYSTEM_PROMPT.md`'s Non-Negotiable Behaviors list without
+  very strong justification and a `CHANGELOG.md` entry explaining why —
+  these are the properties (never assume, always cite evidence, be
+  deterministic) that make every other part of this skill trustworthy.