git:20260705.24c90c9 to git:20260709.a45823f

50 added, 16 removed. Audit A to A.

---

name: deepchat-sdd

- description: Use before DeepChat code, configuration, documentation, test, build, feature, issue, refactor, or architecture changes. Classify work into feature SDD, small-bug issue spec, or architecture SDD; optionally sync feature and bug work to GitHub issues with [feature] or [bug] labels when local gh is usable; keep broad documentation cleanup for the separate deepchat-sdd-cleanup skill.

+ description: Use before substantial DeepChat code, configuration, documentation, test, build, feature, issue, refactor, or architecture changes that need a durable spec. Skip trivial style fixes, small localized logic changes, routine docs edits, and simple bugs unless the developer asks for SDD. Classify substantial work into feature SDD, complex-bug issue spec, or architecture SDD; ask before optional GitHub issue sync unless the developer explicitly requested sync.

---

# DeepChat SDD

## When To Use

- Use this skill before changing DeepChat source code, configuration, tests, docs, build scripts, release workflows, or project structure.

+ Use this skill before substantial DeepChat source code, configuration, tests, docs, build

+ scripts, release workflows, or project structure changes that need shared context or a durable

+ decision record.

+ Skip SDD for trivial or tightly localized work unless the developer explicitly asks for it:

+ - visual/style fixes, copy changes, and small UI layout adjustments

+ - simple localized logic changes with a clear owner module

+ - routine docs edits that do not change project direction

+ - release metadata already covered by the release flow

+ If the scope is unclear, inspect first and then ask whether SDD is wanted instead of creating

+ artifacts by default.

## Classify The Goal

Create one kebab-case folder per goal:

- - New capability, user-visible behavior, integration, or tool: `docs/features/<goal>/`

- - Small bug, regression, failing test, CI failure, reliability problem, or prompt/runtime issue:

+ - New capability, user-visible behavior, integration, or tool large enough to need a shared plan:

+ `docs/features/<goal>/`

+ - Complex bug, regression, failing test, CI failure, reliability problem, or prompt/runtime issue:

`docs/issues/<goal>/`

- Refactor, migration, dependency boundary, shared contract, runtime architecture, or cross-module

design: `docs/architecture/<goal>/`

If one request contains multiple independent goals, split them into separate folders. Keep current architecture reference docs such as `docs/architecture/agent-system.md` in place; use subfolders for new architecture targets.

- Treat a bug as small only when the failure is narrow, the owner module is clear, and the fix does not

- introduce a new user-visible capability, data migration, public contract, or cross-module redesign.

- If it does, classify the work as feature or architecture instead.

+ Treat a bug as SDD-worthy only when the root cause, blast radius, or fix path is complex enough that

+ future developers benefit from the written record. For simple style defects or obvious local logic

+ fixes, skip `docs/issues/*` and implement directly.

+ If a bug fix introduces a new user-visible capability, data migration, public contract, or

+ cross-module redesign, classify the work as feature or architecture instead.

## Required Artifacts

Feature and architecture goals use the full SDD set:

- `spec.md`: user need, goal, acceptance criteria, constraints, non-goals, open questions

- `plan.md`: implementation approach, affected interfaces, data flow, compatibility, test strategy

- `tasks.md`: ordered tasks that can map to commits or review slices

- Small bug goals use one file only:

+ Complex bug goals use one file only:

- `spec.md`: issue description, impact, root cause or suspected location, fix plan, task checklist,

validation, and linked GitHub issue if one exists

- Resolve every `[NEEDS CLARIFICATION]` marker before implementation. If a requested change is tiny,

- keep the artifact short and concrete.

+ Resolve every `[NEEDS CLARIFICATION]` marker before implementation. If the requested change is tiny,

+ prefer skipping SDD over creating a token artifact.

## GitHub Issue Sync

- For feature and small bug goals only, sync to GitHub when local `gh` is installed and authenticated:

+ Do not sync GitHub issues by default. Issue sync is a follow-up record, not a gate for local SDD or

+ implementation.

+ Only create or link a GitHub issue when the developer explicitly asks, or after asking and getting

+ approval once the SDD artifacts are written or the implementation is complete.

+ Eligible work:

+ - Complex bugs only; simple style defects and obvious local logic fixes should not get issues.

+ - Whole new features or major feature rewrites only; single actions, small behavior tweaks, and

+ ordinary adjustments should not get issues.

+ If eligibility is unclear, ask the developer after the work is understood. Never self-authorize issue

+ creation just because local `gh` is installed and authenticated.

+ When approved:

- Feature issues use the `[feature]` label.

- Bug issues use the `[bug]` label.

- Create the label first if it is missing and `gh` has permission.

- Record the issue URL or number in the SDD artifact.

- If `gh` is unavailable or unauthorized, continue local-only and note that no GitHub issue was

- created.

+ created only when sync was requested or approved.

When creating a PR for linked work, include `Closes #NNN` in the PR body so GitHub closes the issue

automatically after merge.

## Workflow

1. Inspect the current code and docs first.

- 2. Pick the target folder from the classification rules.

- 3. Create or update the required artifact set for that classification.

- 4. Sync a GitHub issue for feature or small bug work when `gh` is usable.

+ 2. Decide whether the work is substantial enough for SDD; skip artifacts for trivial/local changes.

+ 3. Pick the target folder from the classification rules when SDD is needed.

+ 4. Create or update the required artifact set for that classification.

5. Keep the implementation aligned with existing DeepChat patterns:

- main process Presenter boundaries

- typed `shared/contracts/*`

- renderer `api/*Client`

- Vue 3 Composition API and i18n for UI strings

6. For architecture work that changes or replaces a historical feature, update that feature's

retained `spec.md` if it is still a maintained contract.

7. Implement the change after the SDD artifacts are complete.

8. Update `tasks.md` or the issue spec checklist as work lands.

- 9. Run `pnpm run format`, `pnpm run i18n`, and `pnpm run lint` before handoff.

+ 9. Ask whether to sync an eligible GitHub issue only after the docs or implementation clarify the

+ scope, unless the developer already requested issue sync.

+ 10. Run `pnpm run format`, `pnpm run i18n`, and `pnpm run lint` before handoff when app code,

+ tests, i18n, or project docs changed.

## Documentation Hygiene

- Do not perform broad SDD cleanup during ordinary feature, bug, or architecture work.

- Use the separate `deepchat-sdd-cleanup` skill only when the developer explicitly asks to clean or

organize SDD documentation.

- During the current goal, update directly affected historical specs when they remain active

contracts.