USM

Appearance

Report an Issue ​

Found a bug, have a suggestion, or want to give feedback? Choose your path below.

For humans ​

Fastest path

Open a pre-filled GitHub issue — title, template, and labels are ready. Just fill in the details.

The link above opens a new issue with:

  • A pre-filled title and body template
  • The docs and feedback labels
  • Your USM version pre-populated

What makes a good report ​

  • Include the page URL — it helps us find the source .usm file quickly
  • Describe what you expected vs what happened
  • Screenshots welcome — drag and drop into the GitHub issue

For AI agents ​

If you're an AI agent and you've found a bug, inconsistency, or improvement opportunity:

Step 0: Where does the bug live? ​

This project is the USM project: its tracker and the USM upstream tracker are the same place (https://github.com/Smith-Gray-Pty-Ltd/usm/issues). File bugs in this codebase and bugs in the USM tool itself (CLI, MCP tools, generators, schema) there — for tool bugs include the @smithgray/usm version, the command/tool invoked, repro, and expected vs actual.

Step 1: Check the feedback policy ​

Read the project's configured feedback policy in AGENTS.md or the rules file. The default is human-gate: describe the issue to the human and ask before filing.

Step 2: Gather context ​

Before reporting, collect:

bash
# Current page context
usm_read .usm/features/<area>/<feature>.usm

# System map for cross-references
usm_list
usm_search "<relevant keywords>"

Step 3: Report via MCP ​

Use the usm_report_feedback MCP tool with structured context:

json
{
  "kind": "bug",
  "severity": "medium",
  "summary": "Short description of the issue",
  "description": "Detailed description with page URL, .usm file reference, and expected vs actual behavior",
  "page_url": "https://docs.usm.dev/schema-reference",
  "usm_file": ".usm/features/schema/v1.usm"
}

Agent feedback protocol

The project's feedback policy (configured via usm feedback) governs how agents report issues. Never create ad-hoc tracking files at the repo root. The canonical location for structured feedback is .usm/feedback/.

Prefer to fix it yourself? ​

All docs are generated from .usm/ source files. Edit the relevant .usm file and submit a PR — the docs will regenerate automatically.