@rashidee/co2 1.2.5

package/plugin/skills/util-updprd/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: util-updprd
+model: claude-opus-4-8
+effort: high
+description: >
+  Apply a free-form requirement change to the PRD.md files of a CO2 project. Takes a
+  human-written prompt describing NEW requirements or updates to existing ones, analyzes
+  the PRD.md of every custom application to determine which applications, modules and
+  subsections (User Story, Non Functional Requirement, Constraint, Reference, Test) are
+  impacted, and decides for each impacted item whether to ADD, CANCEL or MODIFY it.
+  Automatically classifies the change complexity per application as major, minor or patch,
+  computes the next semantic version, and writes the new/updated items under a NEW version
+  tag layered on top of the existing versions in each PRD.md — never rewriting or deleting
+  prior versions. Cancelled items are struck through in place and recorded in the new
+  version. New items are tagged with unique IDs (via util-ustagger) and a CHANGELOG.md
+  entry is appended per impacted application. Presents an impact plan for human
+  confirmation before writing (skippable with `--auto-approve` for orchestrated runs).
+  ALWAYS stops after updating the PRDs and hands back for human review — it never chains
+  into conductor-feature-prepare / -develop / -defect or any generator skill.
+  Trigger on keywords: "update PRD", "update the PRD", "add requirement", "new requirement",
+  "change requirement", "update requirements", "add user story", "cancel user story",
+  "modify user story", "add NFR", "add constraint", "requirement update", "bump PRD version",
+  "new version of requirements", "apply this requirement", "we now need", "the client wants".
+  Accepts a free-form change prompt as the main argument, with optional `application:<app>`
+  and `module:<module>` scope filters
+  (e.g., `/util-updprd "Add SSO login for all users"`,
+  `/util-updprd "Corridor codes must be unique" application:hub_middleware`).
+---
+
+# Util Update PRD
+
+Take a free-form requirement change written by a human and apply it to the PRD.md files across
+a CO2 project. The skill figures out **what changed**, **which applications/modules are
+impacted**, **whether each change is an add / cancel / modify**, and **how big the change is**
+(major / minor / patch) — then layers the change onto each impacted PRD.md as a **new version
+on top of the existing versions**, leaving all prior versions untouched.
+
+This skill is the counterpart to the human-authored PRD: instead of a person hand-editing
+requirements, they describe the change in plain language and this skill applies it consistently
+and traceably across every affected application.
+
+## Inputs
+
+```
+/util-updprd "<free-form requirement change>" [application:<app>] [module:<module>] [--auto-approve]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<prompt>` | Yes | Free-form description of the new requirement(s) or the update(s) to existing ones. May describe multiple discrete changes at once, and may explicitly say something should be removed/cancelled. |
+| `application:<app>` | No | Restrict analysis to a single application. If omitted, **all** custom applications are analyzed and only the impacted ones are changed. |
+| `module:<module>` | No | Hint/restrict the change to a specific module. If omitted, the impacted modules are inferred. |
+| `--auto-approve` | No | Skip the Phase 3 confirmation checkpoint and apply the plan directly. Intended for orchestrated/autonomous runs where interactive confirmation is not possible. Without this flag, the skill presents the plan and waits for the human to confirm before writing. |
+
+Example invocations:
+- `/util-updprd "Every user must be able to reset their own password from the login screen"`
+- `/util-updprd "Drop the CSV export from the dashboard — it is being replaced by scheduled email reports" application:hub_middleware`
+- `/util-updprd "Corridor codes must be globally unique and are now case-insensitive" application:hub_middleware module:corridor`
+- `/util-updprd "Add audit logging for all admin actions" --auto-approve`
+
+### Application Resolution
+
+Same rules as the other CO2 skills:
+1. List root-level application folders (with or without a numeric prefix, e.g. `1_hub_middleware`, `mainapp`).
+2. Strip any leading `<number>_` prefix.
+3. Match the `application:` value case-insensitively (accept `snake_case`, `kebab-case`, title-case).
+4. If `application:` is given but does not match, list available applications and **stop**.
+5. If `application:` is omitted, the candidate set is **every** custom application folder that has a `context/PRD.md`.
+
+### Auto-Resolved Paths (per application)
+
+| File | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+| CHANGELOG.md | `<app_folder>/CHANGELOG.md` |
+
+## Pre-Requisite: CLAUDE.md (already in context)
+
+CLAUDE.md is loaded automatically at session start. Use it as the **source of truth for what
+applications and modules exist**. This skill NEVER invents new applications or modules — modules
+are governed by CLAUDE.md and PRD.md is synced from it by `util-projectsync`. If a change
+requires a module or application that does not yet exist (see Boundary Rules), report it as a
+follow-up action instead of creating it here.
+
+## How Versions Work in PRD.md (read this before editing)
+
+Every subsection in a module carries one or more version tags, each on its own line, with the
+items for that version listed below it. New versions are **appended** below older ones —
+older version blocks are immutable:
+
+```markdown
+### User Story
+[v1.0.0]
+- [USHM00003] As a user, I want to log in so that I can access my data.
+[v1.1.0]
+- As a user, I want to reset my own password so that I don't need to call support.
+```
+
+The versioning semantics (from the PRD.md `# Context` section) are:
+
+| Level | When to use | Version change |
+|-------|-------------|----------------|
+| **major** | A significant change that alters the overall understanding of a module or the system — a new module-scale capability, a fundamental behavior/purpose change, cancelling core user stories, or a Design-System / Architecture-Principle change. | `X+1 . 0 . 0` |
+| **minor** | A change that affects some details but not the overall understanding — adding new user stories / NFRs / constraints / references / tests to existing modules, or extending existing behavior with new fields or rules. | `X . Y+1 . 0` |
+| **patch** | A small change that does not affect understanding — clarifying wording, fixing a typo, tightening a constraint without changing its meaning, or fixing a reference link. | `X . Y . Z+1` |
+
+**One new version per application per run.** All impacted subsections across all impacted
+modules of a single application receive the **same** new version tag. The bump level for that
+application is the **highest-severity** change among everything affecting it (one major change
+makes the whole application bump major, even if the other changes are patches).
+
+## Workflow
+
+### Phase 1 — Understand the Change
+
+1. Read the `<prompt>`. Decompose it into a list of **discrete changes**. A single prompt may
+   contain several (e.g., "add password reset AND remove CSV export" is two changes).
+2. For each discrete change, determine its **operation** and **artifact type**:
+   - **Operation**: `ADD` (a brand-new requirement), `CANCEL` (an existing requirement is no
+     longer valid), or `MODIFY` (an existing requirement changes — treated as CANCEL of the old
+     wording + ADD of the revised wording so history is preserved).
+   - **Artifact type**: which subsection it belongs in — `User Story`, `Non Functional
+     Requirement`, `Constraint`, `Reference`, or `Test`. A behavioral feature is usually a User
+     Story; a performance/security/availability rule is an NFR; a hard limitation or business
+     rule is a Constraint; a pointer to an external doc/message/spec is a Reference; a
+     verification instruction is a Test. One discrete change may produce items in more than one
+     subsection (e.g., a new feature = a User Story + a Test).
+3. If the prompt is genuinely ambiguous about intent (add vs cancel, or which behavior), note
+   the ambiguity — it will be surfaced in the Phase 3 plan for the user to resolve. Do not guess
+   silently on high-impact interpretations.
+
+### Phase 2 — Impact Analysis
+
+For each candidate application (all, or the `application:`-filtered one):
+
+1. Read `<app_folder>/context/PRD.md`. Parse module sections (`## <Module>` under
+   `# System Module` / `# Business Module`) and, within each, the subsections and their
+   existing tagged items.
+2. Read the application's modules from CLAUDE.md (source of truth) to know the full module set.
+3. Map each discrete change to the application's module(s) by matching on:
+   - Entities, roles, screens, and domain nouns mentioned in the change vs. those already
+     described in each module's user stories / NFRs / constraints.
+   - Explicit `module:` hint if provided (restrict to that module but still check cross-module
+     references).
+   - Cross-application relevance: a change like "all users must use SSO" may impact **several**
+     applications — include each one it genuinely affects.
+4. For CANCEL / MODIFY operations, locate the **exact existing item(s)** (by ID and wording) that
+   the change supersedes. If no matching item exists, downgrade the operation to `ADD` (you can't
+   cancel something that isn't there) and note it.
+5. Produce, per application, the set of `(module, subsection, operation, item text or target ID)`
+   entries. An application with zero entries is **not impacted** and will be left untouched.
+
+### Phase 3 — Classify Version & Present the Plan
+
+For each **impacted** application:
+
+1. Discover the current highest version: scan PRD.md for all `[vX.Y.Z]` tags **and**
+   CHANGELOG.md `## vX.Y.Z` headings; take the semantic-version maximum. If none exist, treat
+   the baseline as `v1.0.0`.
+2. Classify the bump level using the table in "How Versions Work" — pick the highest severity
+   across all changes affecting this application.
+3. Compute the new version by applying the bump to the highest version
+   (e.g., highest `v1.2.3` + minor → `v1.3.0`; + major → `v2.0.0`; + patch → `v1.2.4`).
+
+Then present a consolidated **Impact Analysis & Change Plan** and **wait for confirmation**
+before writing anything (this is a cross-cutting, hard-to-reverse edit):
+
+```
+## PRD Update Plan
+
+Change prompt: "<the prompt>"
+
+### hub_middleware  (v1.2.3 → v1.3.0, MINOR)
+| Module   | Subsection  | Op     | Item |
+|----------|-------------|--------|------|
+| User     | User Story  | ADD    | As a user, I want to reset my own password ... |
+| User     | Test        | ADD    | Verify password reset email is delivered ... |
+| Dashboard| User Story  | CANCEL | [USHM00021] ... CSV export ... |
+
+### hc_adapter  (not impacted)
+
+### ⚠ Follow-ups
+- Change "add real-time chat module" needs a new module `Chat` that does not exist in CLAUDE.md.
+  Add it to CLAUDE.md and run /util-projectsync first, then re-run this skill.
+```
+
+**Confirmation gate:**
+- If `--auto-approve` is **not** set: present the plan and **stop until the human confirms**. Do
+  not write any file before confirmation. If the human amends the plan, apply the amended version.
+- If `--auto-approve` **is** set (orchestrated/autonomous run): skip the wait and proceed directly
+  to Phase 4, but clearly log every decision and every ambiguity you resolved so the human can
+  audit them afterward.
+
+### Phase 4 — Apply the Changes
+
+For each impacted application, edit `<app_folder>/context/PRD.md`. **Never modify or delete any
+existing version block, tag, or item** — only append and (for cancellations) strike through.
+
+**ADD** — for each new item:
+- Locate the target subsection in the target module.
+- If the new version tag `[v{new}]` is not yet present in that subsection, append it on its own
+  line **after** the last existing version block of that subsection.
+- Append the new item as a plain, **untagged** top-level bullet under `[v{new}]`:
+  `- As a user, I want to reset my own password so that I don't need to call support.`
+  (User Stories must follow the Agile "As a … I want … so that …" form. Leave the item untagged —
+  Phase 5 assigns the ID.)
+
+**CANCEL** — for each cancelled item:
+- Find the existing item under its original version block. Wrap its text (keeping its ID) in
+  strikethrough and append a cancellation marker, editing it **in place**:
+  `- ~~[USHM00021] As a user, I want to export the dashboard to CSV ...~~ [CANCELLED v1.3.0]`
+- Under the `[v{new}]` block of the same subsection, add a note bullet recording the removal:
+  `- [CANCELLED] [USHM00021] — CSV export removed; superseded by scheduled email reports.`
+  (This note already contains the ID, so util-ustagger will skip it.)
+
+**MODIFY** — treat as CANCEL of the old wording plus ADD of the new wording:
+- Strike through the old item in place with `[SUPERSEDED v{new}]` instead of `[CANCELLED v{new}]`.
+- Add the revised item as a fresh untagged bullet under `[v{new}]` (it gets a new ID in Phase 5).
+- Add a note bullet under `[v{new}]` linking them:
+  `- [SUPERSEDED] [USHM00007] → revised below (case-insensitive corridor codes).`
+
+Formatting discipline:
+- Preserve all existing content, indentation, blank lines, and separators (`---`) exactly.
+- Only add top-level bullets for new items; use sub-bullets for their supporting detail if needed.
+- Keep the new version tag identical across every subsection you touched in this application.
+
+### Phase 5 — Tag New Items
+
+After all edits for an application are written, assign IDs to the newly added (still untagged)
+items by invoking the tagging skill with the application and the **new** version:
+
+```
+Skill(skill: "util-ustagger", args: "<application> <new-version>")
+```
+
+util-ustagger tags every untagged top-level bullet, continues the running numbers per category,
+and skips items that already contain an ID (including the `[CANCELLED]` / `[SUPERSEDED]` notes).
+Run it once per impacted application.
+
+### Phase 6 — Record in CHANGELOG.md
+
+For each impacted application, append an entry to `<app_folder>/CHANGELOG.md`:
+
+1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
+   ```markdown
+   # Changelog
+
+   - This file tracks all skill executions by version for this application.
+   - The highest version recorded here is the current application version.
+   - Skills MUST NOT execute for a version lower than the highest version in this file.
+
+   ---
+   ```
+2. Search for a `## {new-version}` heading.
+3. If it **exists**, append a new row to its table. If it **does not exist**, insert a new
+   section after the `---` below the context header and before any existing `## vX.Y.Z` section
+   (newest-first ordering), with a table header and the first row.
+4. Row format:
+   `| {YYYY-MM-DD} | {application_name} | util-updprd | {impacted modules or "All"} | {N added, M cancelled, K modified — one-line summary} |`
+5. **Never modify or delete existing rows.** The new version is always higher than the previous
+   highest, so it satisfies every downstream skill's version gate.
+
+### Phase 7 — Output Summary
+
+Print a summary table of everything applied:
+
+```
+## PRD Update Summary
+
+| Application    | Version        | Level | Added | Cancelled | Modified | Modules Touched      |
+|----------------|----------------|-------|-------|-----------|----------|----------------------|
+| hub_middleware | v1.2.3 → v1.3.0| MINOR | 2     | 1         | 0        | User, Dashboard      |
+| hc_adapter     | (not impacted) | —     | 0     | 0         | 0        | —                    |
+
+### Follow-ups (for the human to run after review — NOT run automatically)
+- <any module/application that must be added to CLAUDE.md + util-projectsync first>
+- Recommended: run /util-usanalyzer <app> to quality-check the updated requirements.
+- When you are satisfied with the updated PRDs, regenerate artifacts with
+  /conductor-feature-prepare <app> version:<new-version>, then implement.
+```
+
+### STOP — Hand Back to the Human
+
+This skill's job **ends** once the PRD.md files are updated, new items tagged, and CHANGELOG.md
+appended. **Do NOT continue into any conductor skill** (`conductor-feature-prepare`,
+`conductor-feature-develop`, `conductor-defect`) or any `modelgen-*` / `mockgen-*` / `specgen-*` /
+`testgen-*` skill. Requirement changes must be reviewed by a human before any downstream artifact
+is generated or code is written. This is true **even under `--auto-approve`** — auto-approve only
+skips the *plan* confirmation, it does NOT authorize downstream execution. Print the summary and
+the follow-ups (as manual, human-triggered next steps) and stop.
+
+## Boundary Rules (what this skill does NOT do)
+
+- **Never create a new module.** Modules come from CLAUDE.md. If a change needs a module that
+  doesn't exist, report it as a follow-up (update CLAUDE.md, run `util-projectsync`, then re-run).
+- **Never create a new application.** Out of scope — report it as a follow-up.
+- **Never touch downstream artifacts** (models, mockups, specs, tests under `context/*`). This
+  skill only edits PRD.md. Regenerating artifacts for the new version is the job of
+  `conductor-feature-prepare` — but that is a **separate, human-triggered** run after review, not
+  something this skill invokes.
+- **Never auto-chain into conductor or generator skills.** After updating the PRDs, stop and hand
+  back to the human (see "STOP — Hand Back to the Human"). Even in `--auto-approve` mode, the skill
+  applies the PRD changes and stops; it never starts development, preparation, or defect skills.
+- **Never rewrite or delete history.** Prior version blocks, tags, and items are immutable;
+  cancellations are strikethroughs, not deletions.
+
+## Important Rules
+
+- **Layer, don't overwrite.** Every change lands under a NEW version tag appended below existing
+  versions. Existing `[vX.Y.Z]` tags and their items are never modified (except adding
+  strikethrough + a cancellation marker to a cancelled item's line).
+- **One coherent version per application per run**, applied uniformly to every subsection touched.
+- **Bump = highest severity.** If any change to an application is major, the application bumps
+  major; otherwise minor if any change is minor; otherwise patch.
+- **Leave IDs to util-ustagger.** Insert new items untagged; never hand-assign ID codes — that
+  risks collisions with the running counters ustagger maintains.
+- **Preserve existing tags and formatting exactly**, including `[USHM…]`/`[NFRHM…]` codes and
+  version tags.
+- **Only impacted applications are changed.** Applications with no matching modules are reported
+  as "not impacted" and left byte-for-byte unchanged.
+- **Surface ambiguity, don't bury it.** When intent is unclear, put it in the plan and (when
+  interactive) let the user decide before writing.
+- **CANCEL requires an existing target.** If the item to cancel/modify can't be found, downgrade
+  to ADD and note the discrepancy rather than fabricating a strikethrough.

package/plugin/skills/util-usanalyzer/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: util-usanalyzer
+model: claude-sonnet-4-6
+effort: medium
+description: >
+  Analyze PRD.md files for quality issues: incomplete sentences, non-existent references,
+  cross-module inconsistencies, contradictory requirements, duplicate roles, design system
+  validation, architecture principle violations, and process flow coverage gaps. Validates
+  bi-directional coverage between User Stories/NFRs and High Level Process Flows — detects
+  modules not covered by any process flow and process flow steps not covered by any User
+  Story or NFR. Adds inline [TODO] annotations directly into the PRD.md file for each
+  issue found.
+  Trigger on keywords: "analyze user story", "analyze user stories", "check user story quality",
+  "validate user stories", "find user story issues", "audit user stories", "review user stories",
+  "check requirements quality", "find inconsistencies", "find contradictions".
+  Accepts an application name as input (e.g., `/util-usanalyzer mainapp`,
+  `/util-usanalyzer "Main App"`).
+---
+
+# Util US Analyzer
+
+Analyze PRD.md files for quality issues and add `[TODO]` annotations for each issue found.
+
+## Input Resolution
+
+This skill requires one mandatory argument: `<application>`.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<application>` | Yes | Application name — matched against root-level application folders |
+| `<module>` | No | Optional module name to limit analysis to a single module |
+
+### Application Folder Resolution
+
+1. List root-level application folders that may have a numeric prefix (e.g., `1_hub_middleware`, `2_hc_adapter`) or no prefix (e.g., `mainapp`)
+2. Strip the leading `<number>_` prefix from each folder name if present (e.g., `1_hub_middleware` -> `hub_middleware`)
+3. Match the provided application name **case-insensitively** against the stripped folder names
+4. Accept `snake_case`, `kebab-case`, or title-case input (e.g., `hub_middleware`, `hub-middleware`, `Hub Middleware` all match `1_hub_middleware`)
+5. If no match is found, list all available application names and **stop**
+
+### Auto-Resolved Paths
+
+| File | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+
+Example invocations:
+- `/util-usanalyzer mainapp`
+- `/util-usanalyzer "Main App"`
+- `/util-usanalyzer mainapp module:Home`
+
+## Workflow
+
+### 1. Read and Parse PRD.md
+
+Read the entire PRD.md file and parse its structure:
+- Identify all module sections (delimited by `## <Module Name>` headers under `# System Module` or `# Business Module`)
+- Within each module, identify subsections: `### User Story`, `### Non Functional Requirement`, `### Constraint`, `### Reference`, `### Test`, `### Bug`
+- Record line numbers for every item for precise TODO annotations
+- Parse the following top-level extended sections if they exist:
+  - `# Design System` — extract referenced file paths and any inline declarations
+  - `# Architecture Principle` — extract all declared architectural patterns and principles
+  - `# High Level Process Flow` — extract all process flow entries (inline or external file references). For external references (e.g., `- Flow Name: Refer to [file.md](path/to/file.md) for the high level process flow`):
+    - Extract the flow name (text before the colon)
+    - Extract the referenced file path from the markdown link
+    - Resolve the path relative to PRD.md's location
+    - Read the external file and parse its `# Process/System Flow` section (ordered steps) and `# Statuses` section (per-application status tables)
+    - If the external file does not exist, flag the reference line as `BAD_REF` and skip further analysis of that flow
+
+### 2. Collect All Roles
+
+Scan the entire document and collect every role mentioned in user stories (the part after "As a" / "As" and before the comma or "I want"). Build a normalized role registry mapping each unique role to its canonical form and the line numbers where it appears.
+
+### 3. Collect All Cross-References
+
+Scan the entire document for:
+- References to other modules (e.g., mentions of `Batch Job`, `Audit Trail`, `Headcount`, etc.)
+- References to external documents or sections (e.g., `[PROJECT.md](../PROJECT.md)`)
+- References to pages, sections, or features by name within user stories, NFRs, constraints
+
+Build a registry of all outbound references per module.
+
+### 4. Run Analysis Checks
+
+**Skip empty modules entirely.** If a module has no content in any of its subsections (User Story, Non Functional Requirement, Constraint, Reference are all empty — no bullet items), skip that module completely. Do not flag empty sections or run any checks on empty modules.
+
+Execute the following checks in order. For each issue found, record the line number, issue category, and a description.
+
+#### 4.1 Incomplete User Stories
+
+Check every top-level bullet under `### User Story` sections:
+- Must follow the Agile format: **"As a [role], I want [feature] so that [benefit]"** or **"As [role], I want [feature] so that [benefit]"**
+- Flag items missing "I want" clause
+- Flag items missing "so that" clause (benefit/justification)
+- Flag items that appear to be truncated or end abruptly (e.g., ending with a colon but no sub-bullets, or trailing whitespace with no content)
+**Exception:** User stories that end with a colon (`:`) followed by sub-bullets describing the detail are acceptable — they provide the "what" through their sub-items. Only flag these if the sub-bullets are missing.
+
+#### 4.2 Non-Existent References
+
+For each reference found in step 3:
+- If it references an external file (e.g., `[PROJECT.md](../PROJECT.md)`), verify the file exists at the resolved path relative to the PRD.md location
+- If it references a module by name (e.g., backtick-quoted `Batch Job`), verify that module exists as a `## <Module>` section in the document
+- If it references a page or feature (e.g., "redirect to the Headcount list page"), verify that the referenced module exists
+
+#### 4.3 Cross-Module Inconsistencies
+
+For each module, check:
+- If a user story, NFR, or constraint mentions a feature/entity from another module (e.g., "Headcount Fulfillment Status"), verify that feature is actually defined in the referenced module
+- If a user story mentions navigating to another module's page (e.g., "redirect to the Sub Project details page"), verify that view/page is described in the target module's user stories
+- If an NFR or constraint references a concept from another module (e.g., "using `Batch Job`"), verify the referenced module defines that concept
+
+#### 4.4 Contradictory Requirements
+
+Compare requirements within the same module and across modules:
+- Look for NFRs or constraints that directly contradict each other (e.g., one says "will be automatically deleted" while another says "will not be automatically deleted")
+- Look for user stories that grant permissions contradicted by constraints (e.g., a user story allows editing but a constraint says the data is read-only)
+- Look for status values or enums defined differently in different places (e.g., status list in user story differs from status list in constraint)
+- Look for contradictions between NFR and Constraint sections within the same module (e.g., Sub Project NFR says it has status values but Constraint says it will not have status)
+
+#### 4.5 Duplicate Roles
+
+Using the role registry from step 2:
+- Identify roles that are semantically similar but named differently (e.g., "Project Manager" vs "PM", "user" vs "User", "staff" vs "Staff")
+- Check the `## Role` module's constraint section for the canonical role list
+- Flag any role used in user stories that doesn't match the canonical list
+- Flag inconsistent capitalization of the same role (e.g., "a user" vs "a User")
+
+#### 4.6 Design System Reference Validation
+
+If a `# Design System` section exists in PRD.md:
+- Extract the referenced file path (e.g., from `[DESIGN_SYSTEM.md](reference/DESIGN_SYSTEM.md)`)
+- Resolve the path relative to PRD.md's location
+- Verify the referenced file actually exists at the resolved path
+- If the file does not exist, flag as `BAD_REF`
+- If the design system file exists, read it and extract declared UI component patterns, layout conventions, and interaction patterns. Then:
+  - Cross-reference User Stories that describe UI behavior (e.g., "view dashboard", "search for", "view details") with the design system's declared patterns
+  - If a User Story describes a UI interaction or component that directly contradicts a design system declaration (e.g., user story says "popup modal" but design system prohibits modals in favor of inline expansion), flag as `CONTRADICTION`
+  - Only flag clear contradictions — do not flag User Stories that simply omit UI detail, as implementation choices belong in the specification phase
+
+#### 4.7 Architecture Principle Consistency
+
+If an `# Architecture Principle` section exists in PRD.md:
+- Extract declared architectural patterns (e.g., "stateless", "event-driven", "document based database", "message driven", "monolithic", "container based", "file storage using GridFS")
+- Cross-reference with User Stories, NFRs, and Constraints across all modules:
+  - If architecture declares "stateless" but a User Story or NFR implies server-side session storage, flag as `ARCH_VIOLATION`
+  - If architecture declares "document based database" but a User Story, NFR or constraint references SQL joins, foreign key enforcement, or relational schema concepts, flag as `ARCH_VIOLATION`
+  - If architecture declares "event-driven" inter-module communication but a User Story or NFR describes synchronous direct calls between modules, flag as `ARCH_VIOLATION`
+  - If architecture declares "message driven" processing but a User Story, NFR or constraint implies synchronous external API polling for message processing, flag as `ARCH_VIOLATION`
+  - If architecture declares a specific file storage mechanism (e.g., "GridFS in MongoDB") but an NFR or constraint describes a different file storage approach (e.g., local filesystem, S3), flag as `ARCH_VIOLATION`
+  - If architecture declares "monolithic" design but a User Story or NFR describes deploying separate microservices, flag as `ARCH_VIOLATION`
+  - If architecture declares a specific framework/technology (e.g., "Spring Boot", "JTE template engine") but an NFR or constraint references an incompatible technology, flag as `ARCH_VIOLATION`
+- Also check Test sections: if test instructions reference infrastructure or tooling that contradicts architecture principles (e.g., test setup assumes a relational DB when architecture declares document-based), flag as `ARCH_VIOLATION`
+- Only flag clear, unambiguous contradictions — patterns that directly oppose the stated architectural principle
+
+#### 4.8 Process Flow Coverage and Consistency
+
+If a `# High Level Process Flow` section exists in PRD.md:
+
+##### 4.8.1 Parse and Resolve Process Flows
+
+- Each process flow entry in the `# High Level Process Flow` section may be:
+  - **Inline**: A named subsection (e.g., `## Recruitment Agent Sync`) with ordered steps as bullet items directly in PRD.md
+  - **External reference**: A bullet item referencing an external file (e.g., `- Recruitment Agent Sync: Refer to [ra_sync.md](path/ra_sync.md) for the high level process flow`)
+- For external references:
+  - Extract the flow name (text before the colon)
+  - Extract the referenced file path from the markdown link
+  - Resolve the path relative to PRD.md's location
+  - Read the external file and parse its `# Process/System Flow` section (ordered numbered steps) and `# Statuses` section (per-application status tables)
+  - If the file does not exist, flag as `BAD_REF` and skip further analysis of that flow
+- For each successfully parsed flow, build a flow registry containing:
+  - Flow name (e.g., "Recruitment Agent Sync", "Job Demand", "Candidate Registration")
+  - All numbered steps with their descriptions
+  - Application-relevant steps (steps that mention the current application name — inferred from the root folder name, e.g., "Hub Middleware")
+  - Application-specific statuses from the status table (if defined)
+
+##### 4.8.2 Flow → Module Coverage (Forward Check)
+
+For each process flow that has application-relevant steps:
+- **Module existence**: Match the flow name to a module under `# System Module` or `# Business Module`. If no module with a matching name exists, flag the flow entry line in the `# High Level Process Flow` section as `FLOW_COVERAGE` with description: "Process flow '<flow name>' has steps for this application but no corresponding module exists in PRD"
+- **Step-to-NFR coverage**: For each application-relevant step in the flow, verify the corresponding module has an NFR that describes the behavior:
+  - **Message consumption**: If a step describes consuming/listening to messages from a queue, the module must have an NFR describing message queue consumption (e.g., "listen to incoming messages from ... via message queue"). If missing, flag the module's first NFR line as `FLOW_COVERAGE` with description: "Process flow '<flow name>' step <N> describes message consumption but no NFR in module '<module>' covers this behavior"
+  - **Message publishing/forwarding**: If a step describes publishing messages to a queue (forwarding to another system), the module must have an NFR describing message publishing. If missing, flag as `FLOW_COVERAGE`
+  - **Acknowledgement publishing**: If a step describes publishing acknowledgement messages, the module must have an NFR describing acknowledgement behavior. If missing, flag as `FLOW_COVERAGE`
+  - **Data recording**: If a step describes recording/storing messages in the database, the module must have an NFR describing data storage/recording. If missing, flag as `FLOW_COVERAGE`
+  - **Error/failure paths**: If the flow describes error or failure paths (e.g., "response with error if validation failed"), the module must have an NFR or constraint handling that error condition. If missing, flag as `FLOW_COVERAGE`
+- **Cross-entity extraction**: If a flow step implies the application extracts or creates entities managed by other modules (e.g., Job Demand processing that extracts Employer and Recruitment Agent data), verify there is an NFR in either the flow's primary module or the target module describing this extraction. If missing, flag as `FLOW_COVERAGE`
+
+##### 4.8.3 Module → Flow Coverage (Reverse Check)
+
+For each module under `# System Module` or `# Business Module`, scan its NFRs for any of the following message-processing behaviors:
+- Listening to / consuming messages from a message queue
+- Publishing messages to a message queue
+- Publishing acknowledgement messages to a message queue
+- Processing incoming messages from external systems via message queue
+
+If any NFR describes such behavior, verify that:
+- There is a corresponding process flow in the `# High Level Process Flow` section whose name matches or covers this module
+- OR the module's message-processing NFR explicitly references another module's process flow (e.g., an NFR says "updated from Job Demand messages" — this is covered by the Job Demand flow)
+
+If no process flow covers the module's message-processing behavior (directly or via cross-reference), flag the first message-processing NFR in the module as `FLOW_COVERAGE` with description: "Module '<module name>' has message-processing NFRs (e.g., <NFR_ID>) but is not covered by any High Level Process Flow"
+
+**Exceptions — do NOT flag these modules:**
+- Modules whose NFRs only describe internal asynchronous processing (e.g., event listeners triggered within the application, scheduled tasks, internal Spring events) without external message queue interaction
+- Modules whose NFRs explicitly state they receive data as a side effect of another module's message processing (e.g., "Employer information will be extracted from the incoming Job Demand message") — these are indirectly covered by the parent flow
+
+##### 4.8.4 User Story ↔ Process Flow Alignment
+
+For each module that is covered by a process flow (either directly or indirectly):
+- **Data availability check**: If a User Story describes viewing, searching, or managing data (e.g., "search for Employer"), verify that the data referenced in the User Story is delivered to the application by at least one process flow. If a User Story references an entity or data type that no process flow delivers, flag the User Story as `FLOW_COVERAGE` with description: "User story <US_ID> references '<entity/data>' but no process flow delivers this data to the application"
+- **Contradiction check**: If a User Story implies manual creation or modification of data that a process flow says is only received via message queue (read-only from the application's perspective), and no constraint explicitly permits manual override, flag as `CONTRADICTION`
+- **Completeness check**: If a process flow delivers data to the application (e.g., Candidate Registration messages) but the corresponding module has NO User Stories for viewing or managing that data, flag the module's `### User Story` section as `FLOW_COVERAGE` with description: "Process flow '<flow name>' delivers data to this application but module '<module>' has no User Stories for viewing or managing this data"
+
+**Exception**: Modules that are purely system/infrastructure modules (e.g., Authentication, Audit Trail) or modules that only store data as a side effect of another module's processing and have their own explicit User Stories are not required to have a 1:1 User Story for every piece of flow-delivered data.
+
+##### 4.8.5 NFR ↔ Process Flow Status Coverage
+
+For each process flow that defines application-specific statuses in its status table:
+- Each status should correspond to a behavior described by an NFR in the relevant module
+- If a status is defined in the flow's status table for the application but no NFR in the corresponding module describes the behavior that triggers that status (e.g., status `PROCESSED` implies message processing, status `SC_ACKNOWLEDGED` implies publishing acknowledgement), flag the module's first NFR as `FLOW_COVERAGE` with description: "Process flow '<flow name>' defines status '<STATUS_CODE>' for this application but no NFR in module '<module>' describes the behavior triggering this status"
+- Conversely, if an NFR describes a status-producing behavior (e.g., "publish acknowledgement message") but the process flow's status table does not include a matching status for the application, flag the NFR as `FLOW_COVERAGE` with description: "NFR <NFR_ID> describes behavior that should produce a status but process flow '<flow name>' does not define a corresponding application status"
+
+##### 4.8.6 Test Section ↔ Process Flow Alignment
+
+For modules covered by a process flow:
+- If the `### Test` section defines test data or test configuration, verify it is consistent with what the process flow describes
+- If test instructions reference message structures, queue names, or external system interactions, they should be consistent with the process flow's description. If a test references a message type or system interaction not present in any process flow, flag as `FLOW_COVERAGE`
+- Do not flag empty Test sections — test completeness is not the concern of this check
+
+##### 4.8.7 Reference Section ↔ Process Flow Alignment
+
+For modules covered by a process flow:
+- If the `### Reference` section references message structure documents (e.g., `[Job Demand Message](path/to/MESSAGE_JOB_DEMAND.md)`), verify the referenced message type aligns with what the process flow says the application receives
+- If a Reference points to a message structure for a recruitment step that has no process flow defined, flag as `FLOW_COVERAGE` with description: "Reference <REF_ID> points to message structure for '<message type>' but no process flow is defined for this recruitment step"
+
+### 5. Insert TODO Annotations
+
+For each issue found, insert a `[TODO]` annotation in the PRD.md file:
+
+**Placement rules:**
+- Insert the `[TODO]` as a new line **immediately above** (before) the problematic line, at the **same indentation level** as the problematic line
+- If the issue relates to a section-level problem (e.g., empty section, cross-module inconsistency), insert the `[TODO]` as a top-level bullet above the first item after the version tag line
+
+**Format:**
+```
+- [TODO] <CATEGORY>: <description> (line <N>)
+- <the problematic line stays unchanged below>
+```
+
+**Categories:**
+| Category | Code |
+|----------|------|
+| Incomplete User Story | `INCOMPLETE` |
+| Non-Existent Reference | `BAD_REF` |
+| Cross-Module Inconsistency | `CROSS_MODULE` |
+| Contradictory Requirement | `CONTRADICTION` |
+| Duplicate Role | `DUP_ROLE` |
+| Architecture Violation | `ARCH_VIOLATION` |
+| Process Flow Coverage Gap | `FLOW_COVERAGE` |
+
+**Examples:**
+```markdown
+- [TODO] INCOMPLETE: User story is missing content after the colon — no sub-bullets describing what the dashboard shows. Add the dashboard items or remove the trailing colon. (line 25)
+- As Management Team, I want to be able to view the dashboard showing:
+- [TODO] INCOMPLETE: User story is missing "so that [benefit]" clause. Add the business justification. (line 304)
+- [TODO] INCOMPLETE: Possible typo — "be to manage" should likely be "be able to manage". (line 304)
+- As Super Admin, I want to be to manage divisions
+```
+
+### 6. Output Summary
+
+After inserting all TODOs, print a summary table:
+
+```
+## Analysis Summary for <Application Name>
+
+| Category              | Count | Modules Affected                  |
+|-----------------------|-------|-----------------------------------|
+| Incomplete            | X     | Home, Division, ...               |
+| Bad Reference         | X     | ...                               |
+| Cross-Module          | X     | ...                               |
+| Contradiction         | X     | ...                               |
+| Duplicate Role        | X     | ...                               |
+| Arch Violation        | X     | ...                               |
+| Flow Coverage         | X     | ...                               |
+| **Total**             | **X** |                                   |
+
+### Details by Module
+
+#### <Module Name>
+- [INCOMPLETE] line X: <brief description>
+- [BAD_REF] line Y: <brief description>
+...
+```
+
+## Important Rules
+
+- **NEVER remove, modify, or delete existing content.** Only add new `[TODO]` annotation lines.
+- **NEVER modify existing tags** (e.g., `[USHM00003]`, `[v1.0.0]`). These are immutable identifiers.
+- Preserve all existing content, formatting, and indentation exactly.
+- Each TODO must reference the specific line number where the issue was found for easy navigation.
+- Be precise and actionable in TODO descriptions — state what the issue is AND what needs to be done to fix it.
+- Do not flag stylistic preferences — only flag genuine quality issues that could lead to implementation ambiguity.
+- If a module filter is provided, only analyze that module but still check cross-module references involving it.
+- Do not insert duplicate TODOs — if the same issue applies to multiple lines, annotate each line individually but do not repeat the same TODO on the same line.
+- Tables, blank lines, version tags (e.g., `[v1.0.0]`), and section headers are never annotated.
+- When checking for contradictions, consider the full context — an NFR in one module may intentionally override a general rule stated elsewhere. Only flag clear, unambiguous contradictions.
+- When checking roles, the canonical role list is defined in the `## Role > ### Constraint` section under the Role module. Roles not in this list should be flagged.