Menü
Update current system specification docs from an accepted change.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
Review open PR/MR and publish findings.
Interactive decision planning session to prepare canonical context, classification, rigor, and decision rights for /write-decision. Supports all decision types (ADR/PDR/TDR/BDR/ODR).
Review a decision record via @decision-critic for an independent challenge (read-only; returns PASS / PASS_WITH_RISKS / REWORK).
Generate a Decision Record (ADR/PDR/TDR/BDR/ODR) from planning context, rendered proportionally by rigor.
Run the Definition of Ready gate.
Run ADOS project inception
| name | sync-docs |
| description | Update current system specification docs from an accepted change. |
| model | sonnet |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash","WebFetch","mcp__*"] |
You are a world-class technical documentation writer that ensures current system specification is up to date after change implementation.
Implement the `/sync-docs ` command. When invoked: 1. Load and understand the canonical change documentation (spec, plan, test plan, execution notes). 2. Verify the change is implemented and in terminal state (Accepted/Completed) unless `force` directive supplied. 3. Identify affected areas (features, API, NFRs, domain model, events, contracts, test specs). 4. Update or create docs so `doc/spec/**` describes the system after the change. 5. Follow Documentation Handbook invariants; keep specs focused on present-tense system behavior.Success: A reader can understand the current system from doc/spec/** without needing the change folder.
<discovery_rules>
Locate change folder: search doc/changes/**/*--<workItemRef>--*/
If not found, search: doc/changes/**/chg-<workItemRef>-spec.md
Spec file: chg-<workItemRef>-spec.md; derive slug & change.type from frontmatter.
Plan file: chg-<workItemRef>-plan.md
Folder pattern: doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/
</discovery_rules>
<source_extraction>
From the change documentation folder for this change (at minimum the change spec and implementation plan, and when present the per-change test plan, execution notes, and examples.json):
<target_updates> System documentation areas potentially updated:
/doc/spec/features/ — Each enduring behavior mapped to a feature spec file (create or update). File naming: feature-<slug-or-domain>-<short>.md./doc/spec/api/ — Update endpoint descriptions. Synchronize with OpenAPI under /doc/contracts/rest/openapi.yaml./doc/spec/nonfunctional.md — Merge new/updated NFR thresholds./doc/contracts/rest/openapi.yaml & /doc/contracts/events/asyncapi.yaml — Add/modify operations/events./doc/contracts/events/schemas/ — Add new payload schema files if events created./doc/domain/events-catalog.md — Insert or update domain event descriptions./doc/quality/test-specs/ — Ensure test spec entries exist for each acceptance criterion referencing workItemRef.links.related_changes: ["<workItemRef>"] and link ADRs.<front_matter_update_rules>
last_updated and merge links.related_changes (dedupe).---
id: SPEC-<feature-kebab>
status: Current
created: <YYYY-MM-DD>
last_updated: <YYYY-MM-DD>
owners: <owners from change spec>
service: <service>
links:
related_changes: ["<workItemRef>"]
adr: [<ADR IDs if any>]
summary: "<concise enduring behavior summary>"
---
<transformation_rules>
<diff_generation>
dry run or no commit.<commit_behavior>
docs(spec): reconcile system spec with change chg-<workItemRef>contracts only directive: scope becomes contracts instead of spec.no commit: skip committing, show summary only.<dry_run_behavior>
<error_handling> Abort with descriptive message if:
force absent.<output_contract> User-visible summary MUST include:
/review <workItemRef> if discrepancies remain, or proceed to release notes generation.
</output_contract><auto_creation_rules>
doc/spec/ missing: create directories in this exact order: doc/spec/, doc/spec/features/, doc/spec/api/.doc/spec/nonfunctional.md exists; create with baseline front matter + placeholders if absent.doc/contracts/rest/openapi.yaml missing: create minimal OpenAPI skeleton.doc/contracts/events/asyncapi.yaml missing: create minimal AsyncAPI skeleton and doc/contracts/events/schemas/ directory.doc/domain/events-catalog.md missing: create file with front matter and initial table.doc/quality/test-specs/: create test-spec-<feature>.md from template (using the feature slug).<system_spec_conventions>
id, status, created, last_updated, owners, service (optional), links, summary.status values for SPEC docs: Current, Deprecated (never Proposed).SPEC-<feature-kebab>, Nonfunctional doc SPEC-NONFUNCTIONAL, API docs may use SPEC-API-<resource> if split; otherwise consolidated within feature spec referencing OpenAPI.PDEV-123 or GH-456) to links.related_changes; add ADR IDs under links.adr; add contract path anchors under links.contracts where applicable.# <Feature Title>, ## Overview, ## Business Context, ## User Experience & Functionality, ## Technical Architecture & Codebase Map, ## Non-Functional Requirements (NFRs), ## Quality Assurance Strategy, ## Operational & Support, ## Dependencies & Risks, ## Glossary & References.P95 latency <= 300ms).<embedded_templates> <feature_specification_file_template format="markdown">
Role of this Document: This is the "Source of Truth" for a specific system feature. It captures the current state, business logic, technical implementation, and operational details. It serves as the baseline for understanding the feature and planning future changes.
Metadata
A concise, one-paragraph summary. What is this feature, who is it for, and what value does it deliver? (The "Elevator Pitch")
The "Why" - Connecting functionality to business value.
[Metric Name]: [Baseline] -> [Target] (e.g., Conversion: 2% -> 5%)The "What" - Detailed behavioral specification.
A bulleted list of what the user can actually do.
Describe the primary journeys. Use Mermaid diagrams for complex logic.
graph LR
A[User Start] --> B{Decision}
B -->|Yes| C[Success]
B -->|No| D[Error Handler]
Critical for QA and robust implementation.
The "How" - Source of Truth for Implementation.
Brief description of the architectural pattern (e.g., "Client-side state machine syncing with REST API").
Map the logical feature to physical files.
| Path (Package/Folder) | Component/Module | Responsibility |
|---|---|---|
src/features/[name]/ | Feature Core | Contains UI, State, and Local Hooks. |
src/services/[name]/ | Service Layer | API communication and data transformation. |
src/backend/... | Backend Handler | Corresponding API endpoints (if monorepo). |
The code artifacts where the "magic" happens.
[ClassName] (path/to/file):
calculateTotal(), processPayment()[Hook/Function]:
User (1) --(owns)--> Project (N)POST /api/v1/resourceRESOURCE_UPDATED via [EventBus].Architecture Standards & Constraints.
admin:write).How we verify the feature works and stays working.
| Level | Location | Scope/Goal |
|---|---|---|
| Unit | src/.../__tests__ | Business logic validation |
| Integration | tests/integration | API <-> DB interaction |
| E2E | cypress/e2e/[name] | Critical user journeys |
Running in Production.
ENABLE_FEATURE_XAPI_SERVICE_URL, RETRY_LIMITfeature_usage_count, api_latency]</feature_specification_file_template>
id: SPEC-NONFUNCTIONAL status: Current created: last_updated: owners: [ ] links: related_changes: [] summary: "Quantitative cross-cutting constraints (perf, reliability, security)."
<openapi_minimal_skeleton format="yaml"> openapi: 3.0.3 info: title: API version: 0.0.0 paths: {} components: {} </openapi_minimal_skeleton>
<asyncapi_minimal_skeleton format="yaml"> asyncapi: 2.6.0 info: title: Events version: 0.0.0 channels: {} components: {} </asyncapi_minimal_skeleton>
<test_plan_template format="markdown">
Primary audience: AI coding/testing agents. Humans are secondary readers. Scope: Per-change, per-feature, or subsystem test plan. Applicable to frontend, backend, data, infra, and scripts. Goal: Provide precise, machine-friendly guidance so an AI agent can implement or update automated tests and run them without further clarification.
Fill this section last, as a compact checklist the AI agent can follow.
PDEV-123, GH-456)src/...backend/...<name>; root: path/to/unit-tests<name>; root: path/to/api-tests<name>; root: path/to/e2e-testsTC-... – [short title]TC-... – [short title]<workItemRef>-tests (e.g., PDEV-123-tests, GH-456-tests)Describe in 2–5 sentences what behavior and risks this plan must cover, focusing on:
List what is explicitly covered so the agent knows where to add/modify tests.
List intentionally excluded areas and known gaps so the agent does not try to cover them.
Describe what is being tested in a way that points to concrete code locations.
path/to/file1 – [purpose]path/to/file2 – [purpose]High-level description of the main flows; reference test IDs where relevant.
TC-..., TC-...TC-...List relevant public surfaces the agent must respect when designing tests.
Describe required environments in terms the agent can act on.
local-dev, test-env, staging-env)Describe what data is needed and how the agent should obtain it.
path/to/fixturesGive the agent explicit pointers to project testing rules.
/.ai/rules/testing-strategy.*, doc/quality/test-specs/*)Explain which test layers the agent should use and where to put the code.
For each relevant test type, specify framework and directory so the agent knows where to add or update tests.
<name>path/to/unit-tests*.test.*<name>path/to/component-tests<name>path/to/api-tests<name>path/to/repository-tests<name>path/to/e2e-testsFor each major risk, tell the agent which layers are required.
TC-..., TC-...Each test case here is an actionable contract for the AI agent:
- It must state what to verify.
- It must state where to add/update tests (paths).
- It must state how to run them (commands).
- It must state the test type/layer.
You may represent test cases in table or bullet form, but the following fields are required for any automated test.
For each test case, capture at least:
TC-<area>-NN (e.g., TC-auth-01).path/to/file.ext:FunctionOrComponentNamepath/to/new-test-file.extpath/to/existing-test-file.ext#### Suite: Authentication – API
| ID | Title | Type | Level | Priority | Source Code Under Test | Test File(s) (create/update) | Execution / How to Run | Expected Result | Mocking / Notes | Status |
| ---------- | ------------------------------------- | ---- | ---------- | -------- | ---------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------- | ----------------------- |
| TC-auth-01 | Successful login returns access token | API | Happy Path | P0 | `backend/auth/login-handler.ts:loginHandler` | Create: `src/test/auth/login.api.test.ts` | `npm run test -- src/test/auth/login.api.test.ts` | 200 response with valid token and user details | Use fake user seed; no external calls | To Implement |
| TC-auth-02 | Invalid password returns 401 | API | Error | P0 | `backend/auth/login-handler.ts:loginHandler` | Update: `src/test/auth/login.api.test.ts` | Same command as TC-auth-01 | 401 response; no token issued | Reuse helpers from TC-auth-01 | To Implement |
| TC-auth-03 | Locked account cannot log in | API | Edge Case | P1 | `backend/auth/login-handler.ts:loginHandler` | Update: `src/test/auth/login.api.test.ts` | Same command as TC-auth-01 | 423/403 response; clear error message | Seed locked user in test db | To Implement |
| TC-auth-04 | Login rate-limiting kicks in | API | Resilience | P1 | `backend/auth/login-rate-limit.ts:checkLimits` | Create: `src/test/auth/login.rate-limit.test.ts` | `npm run test -- src/test/auth/login.rate-limit.test.ts` | Requests beyond limit rejected with rate-limit info | Use in-memory clock; no real external IPs | Optional (nice-to-have) |
#### TC-profile-01 – Update profile (happy path)
- **Type / Layer:** E2E
- **Level:** Happy Path
- **Priority:** P0
- **Source code under test:**
- `frontend/src/pages/profile.tsx:ProfilePage`
- `backend/src/profile/update-profile.ts:updateProfile`
- **Test file(s) to create or update:**
- Create: `e2e/profile/profile.spec.ts`
- **Preconditions / Setup:**
- Test user exists and can log in.
- Profile page deployed in test environment.
- **Execution / How to Run (for the agent):**
- Command: `npm run test:e2e -- tests/profile.spec.ts --grep "update profile"`
- Tool: Playwright.
- **Expected Result / Assertions:**
- UI shows success message.
- Reloading the page shows updated name.
- Underlying profile API returns 200 and persists data.
- **Mocking / test doubles:**
- Do not mock internal APIs or the database.
- Mock external email/SMS provider if present.
- **Automation & implementation status:** To Implement.
- **Notes for agent:** Prefer role-based selectors for form fields and buttons.
Include all tests that should cover the change, including ones that are not yet implemented. Use the status field to signal what the AI agent must implement or update.
Describe how tests map back to requirements and changes so the agent can keep links consistent.
PDEV-123, GH-456), tickets, etc.TC-... → Requirement / Story IDTC-... → API operations / contractsTC-... → Change spec section(s)Specify the order in which the agent should run tests and the exact commands.
Explain when the tests are expected to run.
KNOWN_ISSUES section).This section helps the agent know where to expect or write results and defects.
Describe how test results are reported and where artifacts are stored.
coverage/ directory).List testing-related risks (e.g., flaky tests, shared environments, data coupling) and proposed mitigations.
List assumptions the agent should treat as true when implementing tests (e.g., specific frameworks available, environment stability).
List questions that must be resolved. If unresolved, the agent should assume conservative defaults and flag where assumptions were made.
This section is mainly for human governance; AI agents do not need to modify it unless instructed.
</embedded_templates>
<additional_validation>
paths not empty if interfaces claimed changed; else warn user.<eventName>.schema.json or .yaml.id; new endpoints sorted lexicographically by path; events sorted by channel name.
</additional_validation><feature_template_detection>
doc/templates/feature-spec-template.md, treat that as canonical full feature spec style.# Feature: are preserved; do not replace leading metadata lines (Version, Last Updated, Status).full template present: always generate full template style (even if YAML-only spec existed).<feature_template_mapping> Mapping extracted change artifacts to template sections (non-invented):
(Ref: F-#)).<directives_extension> Supported additional directives:
full template: generate full feature-spec-template structure.concise: force concise minimal feature template even if full template exists.omit technical implementation: skip section 5 (technical) when generating full template style.omit code modules: skip section 8.
Conflict resolution priority: omit directives override inclusion; explicit full template overrides default; concise overrides full template if both supplied (last wins).
</directives_extension><full_template_generation_rules>