dev-playbooks 1.0.0

package/skills/devbooks-design-doc/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: devbooks-design-doc
+description: devbooks-design-doc: Produce design documents (design.md) for change packages, focusing only on What/Constraints and AC-xxx, without implementation steps. Use when user says "write design doc/Design Doc/architecture design/constraints/acceptance criteria/AC/C4 Delta" etc.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks: Design Document (Design Doc)
+
+## Prerequisites: Configuration Discovery (Protocol Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+Before execution, **must** search for configuration in the following order (stop when found):
+1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
+2. `dev-playbooks/project.md` (if exists) → DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) → Template protocol, use default mappings
+5. If still unable to determine → **Stop and ask user**
+
+**Key Constraints**:
+- If configuration specifies `agents_doc` (rules document), **must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading rules document
+
+## Artifact Location
+
+- Design document: `<change-root>/<change-id>/design.md`
+
+## Documentation Impact Statement (Required)
+
+Design documents **must** include a "Documentation Impact" section declaring the impact of this change on user documentation. This is a key mechanism to ensure documentation stays in sync with code.
+
+### Template
+
+```markdown
+## Documentation Impact
+
+### Documents Requiring Updates
+
+| Document | Update Reason | Priority |
+|----------|---------------|----------|
+| README.md | New feature X requires usage instructions | P0 |
+| docs/user-guide.md | New script Y requires usage documentation | P0 |
+| CHANGELOG.md | Record this change | P1 |
+
+### Documents Not Requiring Updates
+
+- [ ] This change is internal refactoring, does not affect user-visible functionality
+- [ ] This change only fixes bugs, does not introduce new features or change usage patterns
+
+### Documentation Update Checklist
+
+- [ ] New scripts/commands are documented in usage documentation
+- [ ] New configuration options are documented in configuration documentation
+- [ ] New workflows/processes are documented in guides
+- [ ] API/interface changes are updated in relevant documentation
+```
+
+### Trigger Rules
+
+The following change types **require** updating corresponding documentation:
+
+| Change Type | Documents to Update |
+|-------------|---------------------|
+| New script (*.sh) | User guide, README |
+| New Skill | README, Skills list |
+| Workflow changes | Related guide documentation |
+| New configuration options | Configuration documentation |
+| New commands/CLI parameters | User guide |
+| External API changes | API documentation |
+
+## Execution Method
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gates).
+2) Strictly follow complete prompt output: `references/design-doc-prompt.md`.
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution and selects the appropriate running mode.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Process
+
+1. Detect if `proposal.md` exists (input for design document)
+2. Detect if `design.md` already exists
+3. If exists, check completeness (whether it has AC-xxx, whether it has `[TODO]`)
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Create Design** | `design.md` does not exist | Create complete design document |
+| **Supplement Design** | `design.md` exists but has `[TODO]` | Fill in missing sections |
+| **Add AC** | Design exists but AC is incomplete | Add acceptance criteria |
+
+### Detection Output Example
+
+```
+Detection Results:
+- proposal.md: Exists
+- design.md: Exists, has 5 [TODO]s
+- AC count: 8
+- Running mode: Supplement Design
+```
+
+---
+
+## MCP Enhancement
+
+This Skill does not depend on MCP services, no runtime detection required.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+

package/skills/devbooks-design-doc/references/design-doc-prompt.md

@@ -0,0 +1,188 @@
+# Design Doc Prompt
+
+> **Role**: You are the strongest “software architecture brain” — combining Eric Evans (DDD), Martin Fowler (enterprise patterns), and Gregor Hohpe (integration patterns). Your design must meet that expert level.
+
+Highest-priority instruction:
+- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols in it.
+
+You are the **Design Owner**. Your goal is to produce an acceptable, traceable, evolvable **Design Doc** that serves as the golden truth for downstream implementation planning and acceptance testing.
+
+Artifact location (directory convention, protocol-agnostic):
+- This design doc is typically part of a single change package and is recommended at: `<change-root>/<change-id>/design.md`
+- The “Current Truth” lives in `<truth-root>/`; this design doc describes what the change should achieve (and is merged into the truth root when archived)
+- Requirements/Scenarios are not expanded here; use the “spec change prompt” to produce a spec delta (avoid mixing What with Requirements)
+
+Inputs (provided by me):
+- Business/problem background
+- Current state and constraints (if any)
+- Chat history
+- Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
+
+Tasks:
+1) Output a design doc (not an implementation plan, not code).
+2) The doc must be concrete enough to drive acceptance and task decomposition: clear boundaries, contracts, red lines, and acceptance.
+3) To avoid same-source fallacy: define only What/Constraints; do not write How/implementation steps.
+
+Output format (recommended to follow strictly):
+
+> **Lost-in-the-middle optimization**: put key information at the start and end; recall for the beginning/end (~90%) is far higher than the middle (~50–60%).
+
+### Part 1: Key Info Up Front (High Attention Zone)
+
+1) Title + metadata (version/status/last updated/scope/owner/last_verified/freshness_check)
+
+2) **⚡ Acceptance Criteria (front-load!)**:
+   - Number each as `AC-xxx`
+   - Each must be observable and testable with explicit Pass/Fail criteria
+   - Must specify validation method: A (machine judge) / B (tool evidence + human sign-off) / C (manual)
+   - **This is the most important part and must come first**
+
+3) **⚡ Goals / Non-goals + Red Lines (front-load core constraints!)**:
+   - Goals: what the change must accomplish
+   - Non-goals: what is explicitly out of scope
+   - Red Lines: non-negotiable constraints (e.g., must not break backward compatibility)
+
+4) Executive summary (2–3 sentences: goal + core tension)
+
+### Part 2: Background and Design Details (Lower Attention Zone)
+
+5) **Problem Context**:
+   - Why solve this? (business driver / tech debt / user pain)
+   - Where does the current system create friction or bottlenecks?
+   - What happens if we do nothing?
+
+6) Value-chain mapping (Goal → blockers/levers → minimal solution; ask clarifying questions if goals are unclear)
+
+7) Current-state assessment (existing assets / key risks)
+
+8) Design principles (including variation-point identification)
+   - **Variation points are mandatory**: what is most likely to change, and how will it be encapsulated?
+
+9) Target architecture (bounded contexts, dependency direction, key extension points)
+   - **Testability & Seams** (optional but recommended):
+     - **Seams**: list intentional test entry points
+       - Dependency injection points (e.g., constructor args, factory methods)
+       - Replaceable components (e.g., external adapters implementing interfaces)
+       - Observation points (e.g., event publishing, log hooks)
+     - **Pinch points**: high-value test locations
+       - Which modules/classes aggregate multiple call paths?
+       - What downstream paths can tests at those points cover?
+     - **Dependency isolation strategy**:
+       - How are external dependencies (DB/API/third-party) isolated?
+       - Do we need an Anti-Corruption Layer (ACL)?
+     - **Example format**:
+       ```
+       Seams:
+       - OrderService constructor accepts PaymentGatewayInterface (injectable mock)
+       - EventBus.publish() can be observed by test subscribers
+
+       Pinch Points:
+       - OrderService.processOrder() - aggregates 3 paths
+       - PaymentGateway.execute() - aggregates 2 paths
+
+       Dependency isolation:
+       - PaymentGateway → isolated via interface; tests use MockGateway
+       - InventoryDB → isolated via Repository interface
+       ```
+
+10) **Domain Model**:
+   - **Data Model**: list core data objects and tag their type:
+     - `@Entity`: has identity, mutable state, lifecycle tracked (e.g., Order, Customer)
+     - `@ValueObject`: no identity, immutable, descriptive (e.g., Address, Money, DateRange)
+   - **Business Rules**: list business rules separately (do not bury in ACs or code comments)
+     - Each rule has a unique ID (e.g., BR-001)
+     - Specify trigger conditions, constraints, and behavior on violation
+   - **Invariants**: explicitly list invariants (avoid scattering implicitly in code)
+     - Tag them with `[Invariant]` (for downstream acceptance tests and guardrails)
+   - **Context boundaries / integration boundaries**: if external systems/APIs are involved, define an ACL (Anti-Corruption Layer)
+     - Describe transformation points between external and internal models
+     - Note which external changes are isolated by the ACL
+
+11) Core data and event contracts (artifacts, event envelope, `schema_version`, `idempotency_key`, compatibility strategy)
+
+12) Key mechanisms (quality gates, budgeting, isolation, replay, auditing, etc.)
+
+13) Observability and acceptance (Metrics/KPI/SLO)
+
+14) Security, compliance, and multi-tenant isolation
+
+15) Milestones (phased delivery at the design level)
+
+16) Deprecation plan (if replacing/deprecating, specify marking/warnings/removal window)
+
+17) **Design rationale** (optional; recommended for large refactors/architecture changes):
+   - Why this approach vs alternatives?
+   - Key alternatives and why they were rejected
+   - Key technical decisions and justification (e.g., Redis vs PostgreSQL LISTEN/NOTIFY)
+
+18) **Trade-offs**:
+   - What does this design give up? (e.g., strong consistency for high availability)
+   - What known imperfections are accepted?
+   - In which scenarios might this design be unsuitable?
+
+19) **Technical debt** (optional):
+   - **Known debt** introduced or left unresolved
+     - Each item has a unique ID (e.g., TD-001)
+     - Specify type (architecture/code/test/docs)
+     - Cause (time pressure/technical limits/expediency)
+     - Impact and severity (High/Medium/Low)
+   - **Paydown plan**: when and how to repay
+     - Short-term acceptable threshold
+     - Trigger conditions (e.g., user count > X, performance < Y)
+   - **Example format**:
+     ```
+     Technical Debt:
+     - TD-001 [Code] Order service hard-codes payment timeout to 30s
+       - Cause: phase-1 rapid validation; config not extracted
+       - Impact: Medium - requires code changes to adjust timeout
+       - Paydown: move to config before Phase 2
+     - TD-002 [Test] Payment callback lacks integration tests
+       - Cause: mocking third-party payment gateway is complex
+       - Impact: High - callback changes are risky
+       - Paydown: add tests after sandbox environment is available
+     ```
+
+20) Risks and degradation strategy (failure modes + degrade paths)
+
+### Part 3: Strong Ending (High Attention Zone)
+
+21) **⚡ Definition of Done (strong ending!)**:
+   - When is the design considered “done”?
+   - Required gates to pass (tests / lint / build / review)
+   - Required evidence artifacts (what must exist under `evidence/`)
+   - Cross-reference to the ACs at the top
+
+22) Open questions (≤ 3)
+
+Acceptance Criteria writing rules:
+- Each starts with `AC-xxx`
+- Each is observable/testable with explicit Pass/Fail criteria
+- **Non-functional requirements (NFR) must be concrete**:
+  - **No vague adjectives** (e.g., “high performance”, “high availability”, “user-friendly”, “fast”).
+  - **Convert into measurable thresholds** (ranges allowed, e.g., `p99 < 200ms`) or **a clear reference anchor** (e.g., “error component reuses auth module’s UI/UX behavior”).
+  - **Percentiles**:
+    - `p50` (median): 50% requests finish within this time; “typical user” experience
+    - `p95`: 95% requests finish within this time; “most users”
+    - `p99`: 99% requests finish within this time; “almost all users” and exposes tail latency
+    - `p999`: 99.9% requests finish within this time; for high-SLA scenarios
+    - **Why percentiles vs averages**: averages are skewed by outliers and can hide real user experience (e.g., avg 100ms could mean 99% at 50ms and 1% at 5000ms).
+    - **Selection guidance**:
+      - UX metrics: use p95 or p99
+      - SLA/contract constraints: use p99 or p999
+      - Internal monitoring/alerting: monitor p50, p95, and p99 together
+- Must specify validation method:
+  - A: machine judge (tests/static checks/build/smoke)
+  - B: tool evidence + human sign-off (dashboards/reports/log evidence)
+  - C: manual acceptance (UX/product walkthrough)
+- If it cannot be automated: state why and specify what evidence must be retained
+
+Limits:
+- Do not output implementation steps, PR slicing advice, or concrete production code file paths and function bodies.
+- Do not output runnable pseudocode; if you must describe an algorithm, write only Inputs/Outputs/Invariants/complexity bound/degradation strategy.
+
+Additional requirements (for traceability in large projects):
+- Explicitly list affected capabilities/modules/external contracts (names and boundaries only; no implementation)
+- If external interfaces/APIs/events/data structures are involved: specify versioning strategy in the “Core data and event contracts” section (`schema_version`, compatibility window, migration/replay principles)
+- If architecture boundaries change: add an optional **C4 Delta** subsection under “Target architecture” describing what C1/C2/C3 elements were added/modified/removed (full maps are maintained by the C4 map maintainer)
+
+Now output the Design Doc in Markdown. Do not output extra explanations.

package/skills/devbooks-design-doc/references/microservice-design-checklist.md

@@ -0,0 +1,149 @@
+# Microservice Design Checklist
+
+> Use this checklist when the design involves microservices or distributed architecture.
+>
+> This document is **optional guidance**; use it only when the project truly involves microservices/distributed systems.
+
+---
+
+## 1) RPC Location Transparency Trap (must check)
+
+**Core principle**: a remote call is not a local function call—do not hide the complexity.
+
+### 1.1 The design doc must declare
+
+- [ ] **Timeout policy**: timeout per RPC call (recommended 1–5 seconds)
+- [ ] **Retry policy**: max retries, backoff interval, exponential backoff
+- [ ] **Degradation strategy**: behavior when a dependency is unavailable (defaults/cache/error codes)
+- [ ] **Circuit breaker threshold**: failure rate that triggers breaking (recommended 50%)
+
+### 1.2 Anti-pattern checks
+
+| Anti-pattern | Problem | Correct approach |
+|--------|------|----------|
+| RPC without timeouts | One slow service drags down the whole chain | set explicit timeouts (1–5s) |
+| Infinite retries | retry storms overwhelm downstream | max 3 retries with exponential backoff |
+| Synchronous call chaining | A→B→C→D accumulates latency | async or parallelize |
+| Hidden remote calls | caller doesn’t know it’s network IO | make fallibility explicit in API names/types |
+
+### 1.3 Test Owner checklist
+
+- [ ] Tests cover dependency timeouts (mock timeouts)
+- [ ] Tests cover dependency error responses
+- [ ] Tests cover degraded behavior after circuit breaking
+- [ ] Tests cover retry logic (verify max retries)
+
+---
+
+## 2) Distributed Failure Impact Assessment
+
+### 2.1 Failure mode list
+
+| Failure type | Blast radius | Detection | Recovery strategy |
+|----------|----------|----------|----------|
+| Network partition | service A can’t reach service B | health-check timeouts | circuit breaker + degrade |
+| Node crash | single-node outage | heartbeat failures | load-balancer failover |
+| Slow responses | end-to-end latency increases | p99 latency alerts | rate-limit + queue |
+| Data inconsistency | replicas out of sync | reconciliation jobs | retry + compensation |
+
+### 2.2 The design doc must declare
+
+- [ ] Which inter-service dependencies are involved?
+- [ ] What is the blast radius for each dependency failure?
+- [ ] What user-visible behavior occurs under failure?
+- [ ] Do we need chaos testing / failure drills?
+
+---
+
+## 3) Distributed Tracing
+
+### 3.1 Design requirements
+
+- [ ] All RPC calls propagate `trace_id`
+- [ ] Logs include `trace_id`
+- [ ] Events/messages include `trace_id`
+
+### 3.2 Implementation checks
+
+```
+Headers: `X-Trace-Id` / `X-Request-Id`
+Log format: `{"trace_id": "xxx", "message": "...", "timestamp": "..." }`
+Message fields: `{"trace_id": "xxx", "event_type": "...", "payload": {...} }`
+```
+
+### 3.3 Test Owner checklist
+
+- [ ] Tests verify trace_id is propagated across services
+- [ ] Tests verify logs include trace_id
+- [ ] Tests verify error logs can be traced back to the originating request via trace_id
+
+---
+
+## 4) Inter-service Contract Management
+
+### 4.1 Contract definition requirements
+
+- [ ] Use OpenAPI/Proto/AsyncAPI to define contracts
+- [ ] Contract files are version-controlled
+- [ ] Contract changes go through compatibility checks
+
+### 4.2 Contract testing requirements
+
+- [ ] Provider-side contract tests (implementation matches contract)
+- [ ] Consumer-side contract tests (consumer assumptions are correct)
+- [ ] Both sides run tests on contract changes
+
+### 4.3 Breaking change handling
+
+- [ ] Do not delete published APIs directly
+- [ ] Run old and new versions in parallel for at least 2 release cycles
+- [ ] Provide a migration guide and deprecation timeline
+
+---
+
+## 5) Exactly-once and Idempotency
+
+### 5.1 Choosing delivery semantics
+
+| Semantics | Use case | Implementation complexity |
+|------|----------|------------|
+| at-most-once | logs/telemetry (loss allowed) | Low |
+| at-least-once | notifications/analytics (duplicates allowed) | Medium |
+| exactly-once | payments/orders (no loss or duplicates) | High |
+
+### 5.2 Exactly-once implementation checklist
+
+- [ ] Messages include a unique `message_id`
+- [ ] Consumers persist processed `message_id` (DB/Redis)
+- [ ] Duplicate messages return success (idempotent handling)
+- [ ] Tests cover: consume the same message 3 times, execute side effects only once
+
+### 5.3 Test Owner checklist
+
+- [ ] Tests verify duplicates do not cause duplicate side effects
+- [ ] Tests verify retry succeeds after message loss
+- [ ] Tests verify partial failure compensation works correctly
+
+---
+
+## 6) Design Doc Template Additions
+
+In the “Target Architecture” section of `design.md`, add:
+
+```markdown
+### Microservice Design Constraints (if applicable)
+
+#### Service dependency sketch
+- This service → Dependency Service A (timeout 3s, retries 2, degrade to empty list)
+- This service → Dependency Service B (timeout 5s, retries 0, degrade to cached value)
+
+#### Failure modes and degradation
+| Failure scenario | User-visible behavior | Recovery strategy |
+|----------|--------------|----------|
+| Service A unavailable | show “no data” | circuit-break 60s then retry |
+| Service B slow | use cached data | rate-limit when p99 > 1s |
+
+#### Tracing requirements
+- All APIs propagate `X-Trace-Id`
+- Logs are JSON and include `trace_id`
+```

package/skills/devbooks-design-doc/references/privacy-compliance-checklist.md

@@ -0,0 +1,240 @@
+# Telemetry Privacy & Compliance Checklist
+
+Inspired by VS Code’s `telemetry.instructions.md`, this document defines privacy/compliance requirements for telemetry data.
+
+---
+
+## 1) GDPR classification requirements
+
+When `design.md` or a spec delta includes telemetry, you **must** fill in the following fields:
+
+```markdown
+## Telemetry Design
+
+### GDPR Classification
+
+| Field | Value | Notes |
+|------|-----|------|
+| **owner** | @username | data owner (must be a team member) |
+| **isMeasurement** | true/false | whether it’s measurement data (non-PII) |
+| **purpose** | PerformanceAndHealth / BusinessInsight / FeatureInsight | collection purpose |
+| **classification** | SystemMetaData / CallstackOrException / EndUserPseudonymizedInformation | data category |
+| **retention** | 90d / 1y / permanent | retention period |
+| **gdprRequired** | true/false | whether user consent is required |
+
+### Telemetry event definitions
+
+| Event name | Trigger | Data fields | Classification |
+|--------|----------|----------|------|
+| feature.used | when the user uses feature X | `{ featureId, duration }` | SystemMetaData |
+| error.occurred | when an error occurs | `{ errorCode, stack }` | CallstackOrException |
+```
+
+---
+
+## 2) Data classification guidance
+
+### SystemMetaData
+
+**Definition**: system information that does not identify the user.
+
+**Allowed**:
+- OS version
+- App version
+- Feature flag states
+- Performance metrics (latency, memory)
+- Anonymous usage frequency
+
+**Example**:
+```typescript
+// Compliant: system metadata
+telemetry.log('app.startup', {
+  version: '1.0.0',
+  os: 'darwin',
+  memoryUsage: process.memoryUsage().heapUsed,
+});
+```
+
+### CallstackOrException
+
+**Definition**: error information and callstacks.
+
+**Allowed**:
+- Error codes
+- Error messages (must be sanitized)
+- Callstacks (must sanitize file paths)
+
+**Sanitization requirements**:
+- Remove usernames: `/Users/john/` → `/Users/<username>/`
+- Remove project paths: `/project/secret/` → `<project>/`
+- Remove sensitive filenames: `credentials.json` → `<sensitive>`
+
+**Example**:
+```typescript
+// Compliant: sanitized exception
+telemetry.logError('app.error', {
+  errorCode: 'E001',
+  message: sanitizeMessage(error.message),
+  stack: sanitizeStack(error.stack),
+});
+```
+
+### EndUserPseudonymizedInformation
+
+**Definition**: user information that has been pseudonymized.
+
+**Requirements**:
+- Must use one-way hashing
+- Must not be reversible
+- Requires user consent
+
+**Example**:
+```typescript
+// Compliant: pseudonymized user ID
+telemetry.log('user.action', {
+  hashedUserId: sha256(userId + salt), // one-way hash
+  action: 'click',
+});
+```
+
+### PublicNonPersonalData
+
+**Definition**: fully public data that does not include personal information.
+
+**Allowed**:
+- Public configuration options
+- Public API versions
+- Public feature lists
+
+---
+
+## 3) Data you must not collect
+
+| Type | Examples | Reason |
+|------|------|------|
+| Plain PII | name, email, phone | directly identifies users |
+| Location info | GPS, IP address | indirectly identifies users |
+| File contents | user docs, source code | sensitive data |
+| Passwords/tokens | API keys, passwords | security risk |
+| Health info | medical data | sensitive data |
+| Financial info | credit card numbers | sensitive data |
+
+**Detection rules**:
+```bash
+# Detect possible PII collection
+rg "email|phone|name|address|ip" --type ts -g "*telemetry*"
+rg "password|token|secret|key" --type ts -g "*telemetry*"
+```
+
+---
+
+## 4) Event naming conventions
+
+### Standard events (publicLog2)
+
+Used for normal feature usage and performance measurement:
+
+```typescript
+// Naming format: <domain>.<action>
+publicLog2<{ duration: number }>('editor.opened', { duration: 123 });
+publicLog2<{ count: number }>('search.performed', { count: 10 });
+```
+
+### Exception events (publicLogError2)
+
+Used for errors and exceptional conditions:
+
+```typescript
+// Naming format: <domain>.error or <domain>.failed
+publicLogError2<{ code: string }>('editor.error', { code: 'E001' });
+publicLogError2<{ reason: string }>('save.failed', { reason: 'disk_full' });
+```
+
+---
+
+## 5) Code review checklist
+
+When reviewing telemetry-related code:
+
+### Must check
+
+- [ ] **Is GDPR classification complete?**
+  - Is `owner` specified?
+  - Is `classification` correct?
+  - Is `purpose` clear?
+
+- [ ] **Is data sanitized?**
+  - Are usernames removed from file paths?
+  - Are error messages filtered for sensitive data?
+  - Is there any plain PII?
+
+- [ ] **Is naming compliant?**
+  - Do event names follow `<domain>.<action>`?
+  - Do error events use `publicLogError2`?
+
+- [ ] **Is user consent handled?**
+  - For consent-required data, is `telemetryLevel` checked?
+  - Are user privacy settings respected?
+
+### Automated checks
+
+```bash
+# Check for telemetry without classification
+rg "publicLog2|telemetry\.log" --type ts | xargs -I {} grep -L "classification" {}
+
+# Check for sensitive data collection
+rg "(email|phone|password|token)" --type ts -g "*telemetry*"
+```
+
+---
+
+## 6) design.md template snippet
+
+When `design.md` includes telemetry, add:
+
+```markdown
+## Telemetry Impact
+
+### New telemetry events
+
+| Event | owner | classification | purpose | isMeasurement |
+|------|-------|----------------|---------|---------------|
+| feature.x.used | @alice | SystemMetaData | FeatureInsight | true |
+| feature.x.error | @alice | CallstackOrException | PerformanceAndHealth | false |
+
+### Data field definitions
+
+```typescript
+interface FeatureXUsedEvent {
+  duration: number;        // duration (ms)
+  success: boolean;        // success
+  // Do not add: userId, filePath, etc.
+}
+```
+
+### Privacy impact assessment
+
+- [ ] No PII collected
+- [ ] Sensitive paths are sanitized
+- [ ] telemetryLevel settings checked
+- [ ] Privacy Review completed (if required)
+```
+
+---
+
+## 7) Compliance approval workflow
+
+| Data category | Approval requirement |
+|----------|----------|
+| SystemMetaData | no approval required |
+| CallstackOrException | no approval required (must sanitize) |
+| EndUserPseudonymizedInformation | requires Privacy Review |
+| Any new PII | requires Legal Review |
+
+---
+
+## References
+
+- [GDPR data classification guide](https://gdpr.eu/data-protection/)
+- [VS Code telemetry documentation](https://code.visualstudio.com/docs/getstarted/telemetry)
+- [Microsoft Privacy Statement](https://privacy.microsoft.com/)