Util US Tagger

Tag untagged items in PRD.md files with unique 9-character ID codes and validate no duplicates. Covers User Stories, Non Functional Requirements, Constraints, References, and Test instructions.

Version Gate

Before starting any work, resolve the application folder first (see Input Resolution below), then check CHANGELOG.md in the application folder (<app_folder>/CHANGELOG.md):

1. If <app_folder>/CHANGELOG.md does not exist, skip this check (first-ever execution for this application).
2. If <app_folder>/CHANGELOG.md exists, scan all ## vX.Y.Z headings and determine the highest version using semantic versioning comparison.
3. Compare the requested version against the highest version:

• If requested version >= highest version: proceed normally.
• If requested version < highest version: STOP immediately. Print: "Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected." Do NOT proceed with any work.

Input Resolution

This skill requires two mandatory arguments: <application> and <version>.

Application Folder Resolution

1. List root-level application folders that have a numeric prefix (e.g., 1_hub_middleware, 2_hc_adapter)
2. Strip the leading <number>_ prefix from each folder name (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

Example invocations:

• /util-ustagger hub_middleware v1.0.3
• /util-ustagger "Hub Middleware" v1.0.3
• /util-ustagger hub-middleware v1.0.3

Workflow

1. Detect Application Initials

Derive initials from the parent folder name containing PRD.md:

• Strip leading number and underscore prefix (e.g., 1_ from 1_hub_middleware)
• Take the first letter of each remaining word, uppercase
• Examples: 1_hub_middleware -> HM, 2_source_country -> SC, 3_hiring_country -> HC

2. Compute Tag Prefixes

All codes are exactly 9 characters. The prefix is category abbreviation + application initials. Remaining length is zero-padded running number.

3. Scan Existing Tags

Before tagging, scan the entire document for already-tagged items matching the pattern [PREFIX + digits]. Record the highest running number per category to continue from.

4. Tag Untagged Items

For each section (User Story / Functional Requirements, Non Functional Requirement, Constraint, Reference, Test):

• Tag only top-level bullet items (lines starting with - at the section's base indentation)
• Skip sub-bullets (indented lines starting with - )
• Skip already-tagged items (lines containing [USHM, [NFRHM, [CONSHM, [REFHM, [TSTHM etc.)
• Running numbers use interval of 3: 3, 6, 9, 12, 15, ...
• Insert tag as [CODE] immediately after the bullet dash: - [USHM00003] As a...

Section header recognition (case-insensitive matching):

• User Stories: ### User Story, ### Functional Requirements
• NFRs: ### Non Functional Requirement, ## Non Functional Requirement
• Constraints: ### Constraint, ## Constraint
• References: ### Reference, ## Reference
• Tests: ### Test

5. Validate No Duplicates

After tagging, scan the entire document and collect all tag codes. Report:

• Total count per category (US, NFR, CONS, REF, TST)
• Any duplicate codes found (this is an error that must be fixed)
• Confirmation message if no duplicates

6. Output Summary

Print a summary table:

| Category    | Prefix   | Count | Range                    |
|-------------|----------|-------|--------------------------|
| User Story  | USHM     | 35    | USHM00003 - USHM00105   |
| NFR         | NFRHM    | 39    | NFRHM0003 - NFRHM0117   |
| Constraint  | CONSHM   | 13    | CONSHM003 - CONSHM039   |
| Reference   | REFHM    | 6     | REFHM0003 - REFHM0018   |
| Test        | TSTHM    | 4     | TSTHM0003 - TSTHM0012   |
| Duplicates  | -        | 0     | None                     |

Changelog Append

After all tags are successfully applied, append an entry to CHANGELOG.md in the application folder (<app_folder>/CHANGELOG.md):

1. Read <app_folder>/CHANGELOG.md. If it does not exist, create it with:

   # 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.

   ---

1. Search for a ## {version} heading matching the current version.
2. If the section exists: append a new row to its table.
3. If the section 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 new table header and the first row.
4. Row format: | {YYYY-MM-DD} | {application_name} | util-ustagger | All | Tagged user stories, NFRs, constraints, references and tests |
5. Never modify or delete existing rows.

Important Rules

• NEVER remove, modify, or reassign existing tags. Existing tags are immutable — they may already be referenced by module models, specifications, or other documents. Changing them would break traceability.
• Never tag sub-bullets; only top-level bullets under tagged sections
• Never re-tag items that already have a tag code
• New tags must continue from the highest existing running number per category (not restart from 003)
• All codes must be exactly 9 characters
• Running numbers always use interval of 3
• Tables, blank lines, and version tags (e.g., [v1.0.0]) are never tagged
• Preserve all existing content, formatting, and indentation exactly