maintain-discatsharp git:20260811.cc00be2A

Immutable. This exact content is served forever at /api/v1/blob/a72e2c4ab3560a68.

---
name: maintain-discatsharp
description: Review, modify, test, document, or release the DisCatSharp repository. Use for DisCatSharp source changes, API additions and migrations, Discord payload models, serialization, command synchronization, Gateway dispatch, REST behavior, analyzer work, multi-target testing, DocFX generation, release notes, and repository pull requests.
license: MIT
---

# Maintain DisCatSharp

Make evidence-backed changes against the live checkout. Preserve user work, trace every connected behavior that carries a public value, and validate the smallest relevant surface across the supported frameworks.

## Start safely

1. Read the repository's root `AGENTS.md` and `CONTRIBUTING.md`.
2. Confirm the exact checkout, branch, target issue or PR, and working-tree state.
3. Treat existing tracked and untracked changes as user-owned. Never discard, rewrite, or include unrelated work.
4. Re-read files immediately before patching when another person or agent may be editing concurrently.
5. Use live files and current supplied upstream documentation as authoritative. `discatsharp-ai.xml` is a read-only Repomix snapshot and may be stale.

Read [references/repository-map.md](references/repository-map.md) before changing an unfamiliar subsystem.

## Trace the behavior

Do not review a public member or payload field in isolation. Depending on the feature, inspect:

- Input parsing and type mapping.
- Constructors, property setters, validation, and default values.
- JSON serialization/deserialization and `Optional<T>` behavior.
- Manual copies, localization reconstruction, cloning, and builders.
- Equality, synchronization, overwrite, and cache-update decisions.
- REST request models and Gateway payload/event models.
- XML documentation for public, internal, and private symbols, plus conceptual guidance, analyzers, and migrations.
- Focused regression tests for the failure mode.

Mirror Discord's actual contract. Do not add speculative REST enrichment to a Gateway event when its payload already carries the authoritative data.

## Implement consistently

- Follow the repository's C# style, including file-scoped namespaces and existing `this.` usage.
- Preserve compatibility. Discuss breaking changes and prefer the repository's `Deprecated` migration path for public API removal.
- Use exact current upstream documentation when Discord behavior is revision-sensitive.
- Maintain the repository's 100% documentation goal. Every declaration is in scope regardless of visibility, including internal and private types, members, and fields. New and materially changed code must not add undocumented declarations; explain state invariants and ownership rather than restating names, and improve adjacent gaps when practical.
- Keep REST bucket ordering distinct from Gateway dispatch ordering.
- Avoid broad redesign during a focused fix unless a connected correctness path requires it.
- Use `apply_patch` or an equally reviewable edit path and inspect the resulting diff.

## Validate proportionally

Read [references/validation-matrix.md](references/validation-matrix.md), then:

1. Run the smallest relevant test project or filtered regression tests.
2. Cover `net9.0`, `net10.0`, and `net11.0` when the project targets all three.
3. Build the affected package or solution when public/API shape changes.
4. Run `git diff --check` and inspect untracked files separately from the diff stat.
5. For Gateway tests that immediately inspect callbacks, select `SequentialHandlers` or explicitly wait for concurrent handlers to complete.
6. Run broader tests only when the touched dependency surface justifies them.

## Documentation and release work

- Generate documentation with `docfx DisCatSharp.Docs/docfx.json`; do not manually maintain generated API navigation.
- Keep conceptual content discoverable through DocFX rather than hardcoded search-index folder lists.
- Update XML documentation across every affected visibility level and add migration guidance for behavioral or breaking changes.
- Keep `RELEASENOTES.md` as the active cumulative release-cycle notes.
- Treat `CHANGELOG.md` as the stable release index and DocFX changelog pages as the detailed historical record.
- Public releases are created only through the manually dispatched `Release DisCatSharp` workflow.

## Hand off cleanly

- State what changed, what was verified, and any remaining risk.
- Do not claim a timed-out command failed without checking the process or its output.
- Follow the repository's pull-request template and requested draft/merge boundary.
- Never merge, publish a package, enable repository policy, or mutate production infrastructure unless the user explicitly authorizes it.