Adam
/
AyCode.Core
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md

10 KiB
Raw Blame History

Topic Codes — registry for globally-unique issue/TODO/decision IDs

Scope note — workspace meta-tooling: This registry is workspace-configuration, not framework code. It lists topics across any layer (framework, shared libraries, consumer products) because LLM agents operate across the full workspace and need one unified topic list. This is an intentional exception to the Framework-First Design Principle — see AyCode.Core/.github/copilot-instructions.md → Framework-First Design Principle → Exception for workspace meta-tooling. If AyCode.Core is extracted as a standalone framework, this registry is replaced with the new workspace's topic set (typically only LOG, BIN, TOON, XCUT, LLMP — the framework-layer topics).

Canonical registry of topic codes used in issue, TODO, bug, critical, and decision entry IDs across the workspace. ID format: {TOPIC}-{TYPE}-{N}.

Why this registry exists

To make IDs like LOG-I-5, SIG-B-2, XCUT-I-1 globally unique strings — unambiguous when referenced from code comments, cross-file, commit messages, or a future DB migration.

Topic codes

Code Topic Scope Docs location (primary)
LOG LOGGING Logger system: levels, writers, config-reading vs DI factory AyCode.Core/AyCode.Core/docs/LOGGING/ (+ variants in AyCode.Core.Server, AyCode.Services, Mango.Nop.Services)
AUTH AUTH User authentication: bearer tokens, JWT, login flow, hub authorization AyCode.Core/docs/AUTH/
SIG SIGNALR SignalR transport: tags, client base, dispatch, session AyCode.Core/AyCode.Services/docs/SIGNALR/ (+ variant in AyCode.Services.Server)
SBP SIGNALR_BINARY_PROTOCOL Binary wire protocol over SignalR: framing, chunking, argument read AyCode.Core/AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/
BIN BINARY AcBinary serializer: features, format, writers, source generator AyCode.Core/AyCode.Core/docs/BINARY/
TOON TOON Toon serializer: LLM-optimized format with @meta/@types/@data sections AyCode.Core/AyCode.Core/docs/TOON/
GRID MGGRID (grid component) MGGRID component family: layout, CRUD, columns, toolbar, rendering AyCode.Blazor/AyCode.Blazor.Components/docs/MGGRID/
XCUT cross-cutting Issues / TODOs that span ≥2 topics — one canonical home, referenced from others AyCode.Core/AyCode.Core/docs/XCUT/ (canonical; entry can be cross-ref'd from each affected topic file)
LLMP LLM-protocol meta LLM protocol decisions (Decision Log entries only — uses LLMP-DEC-N form) AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md

Type codes

Code Type Used in file Notes
I Issue {TOPIC}_ISSUES.md Concrete concern: spec inconsistency, broken contract, observable edge case
T TODO {TOPIC}_TODO.md Forward-looking planned work: refactor, missing feature, optimization
B Bug {TOPIC}_ISSUES.md (alongside I entries) Confirmed broken behaviour, reproducible, needs a code fix
C Critical {TOPIC}_ISSUES.md or {TOPIC}_TODO.md Severity override — emergency priority, supersedes I/B/T category; body explains type
DEC Decision LLM_PROTOCOL_DECISIONS.md LLMP-only. Append-only protocol decision entries.

Distinctions

  • I vs B: Both tracked together in _ISSUES.md. Use B only when the behaviour is confirmed broken with a reproducer. I covers concerns, inconsistencies, doc drift, edge cases without an active bug.
  • C (Critical): A severity flag, not a category. LOG-C-1 means "logger critical item 1" — body must state whether it's an underlying bug / issue / todo. Prefer C over I/B/T when severity is emergency. Do NOT double-classify (no LOG-IB-1 or similar).
  • DEC: LLMP exception — long form because "LLMP-D-1" is unreadable. Decision Log entries only.

ID format rules

  1. Format: {TOPIC}-{TYPE}-{N} — all uppercase, hyphen-separated.
  2. Sequential number: starts at 1, no zero-padding (LOG-I-1, LOG-I-10, LOG-I-123).
  3. Counter scope: per (topic, type) pair. LOG-I-* and LOG-T-* have independent counters. LOG-B-* has its own counter (separate from LOG-I-*).
  4. Append-only: once assigned, IDs never change. If an entry is reversed or superseded, add a NEW entry that references the prior one — do not renumber.
  5. Hash anchor (markdown cross-file refs): lowercase with hyphens preserved (LOGGING_ISSUES.md#log-i-5 — GitHub auto-converts).
  6. No sub-category in ID: legacy prefixes like PROTO-, DISPATCH-, CONN-, DS- are NOT allowed at ID level. Capture sub-category in the entry body header: ## SIG-I-4 [PROTO]: ....

Registry maintenance

To add a new topic code:

  1. Propose the code (2-5 uppercase chars), short and mnemonic.
  2. Check it doesn't collide with C# class-name prefixes (Ac* = AyCode.Core, Mg* = Mango-specific) — the code should be visually distinct from those prefixes.
  3. Add a row to this registry.
  4. Create the topic folder: docs/{TOPIC_FOLDER_NAME}/ with README.md, optional {TOPIC_FOLDER_NAME}_ISSUES.md, {TOPIC_FOLDER_NAME}_TODO.md.
  5. Add a Decision Log entry (LLMP-DEC-N) recording the new topic.

Collision avoidance with class-name prefixes

C# code conventions in this workspace:

  • Ac* — AyCode.Core framework types (e.g., AcLoggerBase, AcBinarySerializer)
  • Mg* — Mango company types (e.g., MgGrid, MgDbTableBase, MgEntityBase)

Topic codes intentionally avoid these 2-char prefixes to prevent visual confusion in mixed content (e.g., MgGrid.cs → GRID-I-1, not MG-I-1).

Examples

LOG-I-5       # logger issue 5
LOG-T-3       # logger TODO 3
LOG-B-1       # logger bug 1 (confirmed broken)
LOG-C-1       # logger CRITICAL — body: underlying bug / issue / todo
SIG-I-4       # SignalR issue 4 (body may note: [PROTO] sub-category)
SBP-T-2       # SignalR Binary Protocol TODO 2
BIN-B-1       # Binary serializer bug 1
TOON-I-3      # Toon issue 3
GRID-T-7      # MgGrid TODO 7
XCUT-I-1      # cross-cutting issue 1 (affects ≥2 topics)
LLMP-DEC-4    # LLM-protocol decision 4 (Decision Log entry)

Cross-references to other files

  • Reference format (cross-file in markdown): LOGGING_ISSUES.md#log-i-5 (filename + hash anchor). Bare ID (LOG-I-5) may be used when context is unambiguous (within the same topic).
  • Code comments: // See LOG-I-5 — bare ID acceptable since it's globally unique.
  • DB natural key (future migration): (topic, type, seq) tuple; or the full string LOG-I-5 as a single column.

Status field conventions

Every entry in _ISSUES.md, _TODO.md, and LLM_PROTOCOL_DECISIONS.md SHOULD carry an explicit Status field. 3 allowed values:

Status Meaning Archive eligible?
Open Active / unresolved (default for new entries); also used for documented-current-behaviour entries that must remain visible No
InProgress Partial work in flight; some scope addressed but more remains No
Closed Done — bug fixed, decision made (won't fix / superseded by another entry / accepted), TODO completed. The body of the entry explains what happened (date, ref, rationale). Yes

Defaults

  • New entries default to Status: Open.
  • For documented current-behaviour entries (accepted limitations / "by design" / "this is how it works"), use Status: Open with an optional body callout: > **Note:** This entry documents accepted current behaviour — not scheduled for change. These never archive (Open status).

Update workflow

When status changes, update the Status line in-place. This is the ONE exception to append-only — the Status field is mutable; entry body / ID / Description remain immutable.

When marking Closed:

  1. Format the Status line as Status: Closed (YYYY-MM-DD) — the inline date is what docs-archive uses to determine the destination year-bucket.
  2. Add a ### Resolution sub-section documenting the closure. Strongly recommended — without it, future readers (and the docs-archive skill on lookup) have no context for "what changed, why, where". Suggested fields:
    • What: one-line summary of the change.
    • Where: code reference (file/class/commit hash) or doc reference (ADR / PR).
    • Why: the rationale (fix / "won't fix because X" / "superseded by LOG-I-Y" / "accepted as-is").
    • Optional: scope, date if different from Status line, related entries.

The body carries the nuance; the Status field only signals archive-eligibility.

Lifecycle: archive

Closed entries are eligible for rotation into year-bucketed archive files (<file>_<year>.md) via the docs-archive skill. Year derived from a date in the entry body. Archive operation is user-invoked — closed entries don't disappear automatically. See AyCode.Core/.github/skills/docs-archive/SKILL.md.

Change history

See the Decision Log (../../../LLM_PROTOCOL_DECISIONS.md) for the introduction of this registry and future topic-code additions.