universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/skills/claude-code/ai-collaboration-standards/anti-hallucination.md

@@ -0,0 +1,215 @@
+# Anti-Hallucination Guidelines
+
+> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/ai-collaboration-standards/anti-hallucination.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-24
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides guidelines to prevent AI hallucination and ensure evidence-based responses.
+
+---
+
+## Core Principles
+
+### 1. Evidence-Based Analysis Only
+
+**Rule**: Only analyze and reference content that has been explicitly provided or read.
+
+**Guidelines**:
+- ✅ Analyze code files that have been read using file reading tools
+- ✅ Reference documentation that has been fetched
+- ✅ Cite configuration files that have been inspected
+- ❌ Do NOT speculate about APIs, functions, or configurations not seen
+- ❌ Do NOT assume framework behavior without verification
+- ❌ Do NOT fabricate requirement details
+
+---
+
+### 2. Explicit Source Attribution
+
+**Rule**: All references must include source type, location, and verifiability information.
+
+#### Source Types
+
+| Source Type | Tag | Reliability |
+|-------------|-----|-------------|
+| Project Code | `[Source: Code]` | ⭐⭐⭐⭐⭐ Highest |
+| Project Docs | `[Source: Docs]` | ⭐⭐⭐⭐ High |
+| External Docs | `[Source: External]` | ⭐⭐⭐⭐ High |
+| Web Search | `[Source: Search]` | ⭐⭐⭐ Medium |
+| AI Knowledge | `[Source: Knowledge]` | ⭐⭐ Low |
+| User Provided | `[Source: User]` | ⭐⭐⭐ Medium |
+
+#### Attribution Format
+
+**For Code References**:
+```
+[Source: Code] file_path:line_number - Description
+```
+
+**For External Documentation**:
+```
+[Source: External] URL - Description (Version: x.x.x, Accessed: YYYY-MM-DD)
+```
+
+**For AI Knowledge**:
+```
+[Source: Knowledge] Topic - Description (⚠️ Requires verification)
+```
+
+#### Version Sensitivity
+
+When referencing libraries, frameworks, or APIs, always include version information:
+
+```
+✅ [Source: External] Next.js App Router (v14.x) - Server Components are the default
+✅ [Source: Code] package.json:12 - Using "express": "^4.18.2"
+❌ "Next.js uses Server Components" (which version?)
+```
+
+---
+
+### 3. Classify Certainty Levels
+
+**Rule**: Clearly distinguish between confirmed facts, inferences, and unknowns.
+
+| Tag | Use When |
+|-----|----------|
+| `[Confirmed]` | Direct evidence from code/docs |
+| `[Inferred]` | Logical deduction from available evidence |
+| `[Assumption]` | Based on common patterns (needs verification) |
+| `[Unknown]` | Information not available |
+| `[Need Confirmation]` | Requires user clarification |
+
+**Examples**:
+
+```
+[Confirmed] src/database/connection.ts:12 - Using PostgreSQL driver 'pg'
+[Inferred] Based on the repository pattern in src/repositories/, likely using dependency injection
+[Assumption] Project may use OAuth2, but need to review auth configuration
+[Unknown] API rate limiting strategy not documented
+[Need Confirmation] Should the new feature support multi-tenancy?
+```
+
+---
+
+### 4. Recommendation Principles
+
+**Rule**: When providing multiple options, always include a recommended choice with reasoning.
+
+| Scenario | Requirement |
+|----------|-------------|
+| 2+ options presented | Must indicate recommended option with reasoning |
+| Clear winner exists | Directly recommend best option with reasoning |
+| Trade-offs exist | Recommend based on current context, explain trade-offs |
+| Cannot determine | Explain what information is needed to make a recommendation |
+
+---
+
+### 5. Prohibited Behaviors
+
+AI assistants MUST NOT:
+
+1. **Fabricate APIs or Function Signatures**
+   - ❌ Do NOT invent method names, parameters, or return types
+   - ✅ DO read the actual source code or ask the user
+
+2. **Assume Requirements**
+   - ❌ Do NOT guess user needs or business rules
+   - ✅ DO ask clarifying questions when requirements are ambiguous
+
+3. **Speculate About Unread Code**
+   - ❌ Do NOT describe functionality of files not reviewed
+   - ✅ DO explicitly state "Need to read [file] to confirm"
+
+4. **Invent Configuration**
+   - ❌ Do NOT assume environment variables, config keys, or database schemas
+   - ✅ DO review actual configuration files
+
+5. **Hallucinate Errors or Bugs**
+   - ❌ Do NOT claim code has issues without evidence
+   - ✅ DO analyze actual code and cite specific lines
+
+6. **Present Options Without Recommendation**
+   - ❌ Do NOT list options and ask user to choose without guidance
+   - ✅ DO always include a recommended choice with reasoning
+
+---
+
+## AI Assistant Workflow
+
+```
+┌─────────────────────────────────┐
+│  User Request Received          │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  Identify Information Needed    │
+│  - Code files?                  │
+│  - Configuration?               │
+│  - Requirements?                │
+└─────────────┬───────────────────┘
+              │
+              ▼
+         ┌────┴────┐
+         │ Available? │
+         └────┬────┘
+              │
+      ┌───────┴───────┐
+      │               │
+     YES              NO
+      │               │
+      ▼               ▼
+┌──────────┐   ┌─────────────┐
+│  Read/   │   │  Ask User   │
+│  Analyze │   │  for Info   │
+└────┬─────┘   └──────┬──────┘
+     │                │
+     ▼                ▼
+┌─────────────────────────────────┐
+│  Tag Response with:             │
+│  - [Confirmed] for facts        │
+│  - [Inferred] for deductions    │
+│  - [Need Confirmation] for gaps │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  Cite Sources (file:line)       │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  Include Recommendation         │
+│  (if presenting options)        │
+└─────────────────────────────────┘
+```
+
+---
+
+## Related Standards
+
+- [Anti-Hallucination Standards](../../../core/anti-hallucination.md)
+- [Certainty Labels Reference](./certainty-labels.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This document is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/claude-code/ai-collaboration-standards/certainty-labels.md

@@ -0,0 +1,124 @@
+# Certainty Labels Reference
+
+> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/ai-collaboration-standards/certainty-labels.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-24
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides reference for certainty labels and source types used in AI responses.
+
+---
+
+## Tag Mapping (English / 中文)
+
+| English Tag | 中文標籤 | Use When |
+|-------------|---------|----------|
+| `[Confirmed]` | `[已確認]` | Direct evidence from code/docs |
+| `[Inferred]` | `[推論]` | Logical deduction from evidence |
+| `[Assumption]` | `[假設]` | Based on common patterns (needs verification) |
+| `[Unknown]` | `[未知]` | Information not available |
+| `[Need Confirmation]` | `[待確認]` | Requires user clarification |
+
+---
+
+## Source Types
+
+| Source Type | Tag | Description | Reliability |
+|-------------|-----|-------------|-------------|
+| Project Code | `[Source: Code]` | Directly read from codebase | ⭐⭐⭐⭐⭐ Highest |
+| Project Docs | `[Source: Docs]` | README, Wiki, inline comments | ⭐⭐⭐⭐ High |
+| External Docs | `[Source: External]` | Official documentation with URL | ⭐⭐⭐⭐ High |
+| Web Search | `[Source: Search]` | Search results (include date) | ⭐⭐⭐ Medium |
+| AI Knowledge | `[Source: Knowledge]` | AI training data (needs verification) | ⭐⭐ Low |
+| User Provided | `[Source: User]` | Information from user conversation | ⭐⭐⭐ Medium |
+
+---
+
+## Usage Examples
+
+### In Technical Documents
+
+```markdown
+## System Architecture Analysis
+
+`[Confirmed]` System uses ASP.NET Core 8.0 framework [Source: Code] Program.cs:1
+`[Confirmed]` Database uses SQL Server [Source: Code] appsettings.json:12
+`[Inferred]` Based on Repository Pattern usage, system likely adopts DDD architecture
+`[Assumption]` Caching mechanism may use Redis (need to confirm config)
+`[Need Confirmation]` Should multi-tenancy be supported?
+```
+
+### In Code Review
+
+```markdown
+## Review Comments
+
+`[Confirmed]` src/Services/AuthService.cs:45 - Password validation lacks brute force protection
+`[Inferred]` Rate limiting may be needed here
+`[Need Confirmation]` Are there other layers of protection already in place?
+```
+
+---
+
+## Best Practices
+
+### 1. Consistency
+
+- Use the same language tags throughout a document (all Chinese or all English)
+- Team should specify preferred language in `CONTRIBUTING.md`
+
+### 2. Source Citation
+
+- Chinese tags still require source citations
+- Format: `[已確認]` statement [Source: Code] file_path:line_number
+
+### 3. Team Agreement
+
+- Decide on Chinese or English tags at project start
+- Document in `CONTRIBUTING.md` or `.standards/` directory
+
+---
+
+## Quick Decision Guide
+
+```
+Did you read the actual code/doc?
+├── YES → [Confirmed] / [已確認]
+└── NO
+    ├── Can you deduce from available evidence?
+    │   ├── YES → [Inferred] / [推論]
+    │   └── NO
+    │       ├── Is it a common pattern?
+    │       │   ├── YES → [Assumption] / [假設]
+    │       │   └── NO → [Unknown] / [未知]
+    └── Does user need to clarify?
+        └── YES → [Need Confirmation] / [待確認]
+```
+
+---
+
+## Related Standards
+
+- [Anti-Hallucination Guidelines](./anti-hallucination.md)
+- [Anti-Hallucination Standards](../../../core/anti-hallucination.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This document is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/claude-code/changelog-guide/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: changelog-guide
+description: |
+  Write and maintain CHANGELOG.md following Keep a Changelog format.
+  Use when: creating changelog entries, preparing releases, documenting changes.
+  Keywords: changelog, release notes, CHANGELOG.md, keep a changelog, 變更日誌, 發布說明.
+---
+
+# Changelog Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/changelog-guide/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-30
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill helps write and maintain CHANGELOG.md files following the Keep a Changelog format, ensuring clear communication of changes to users.
+
+## Quick Reference
+
+### File Structure
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.2.0] - 2025-12-15
+
+### Added
+- Feature description
+
+### Changed
+- Change description
+
+### Fixed
+- Bug fix description
+
+[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
+```
+
+### Change Categories
+
+| Category | When to Use | Example |
+|----------|-------------|---------|
+| **Added** | New features | Add dark mode support |
+| **Changed** | Modifications to existing features | Improve search performance by 50% |
+| **Deprecated** | Features to be removed | Deprecate legacyParse() |
+| **Removed** | Removed features | Remove Node.js 14 support |
+| **Fixed** | Bug fixes | Fix login timeout issue |
+| **Security** | Security patches | Fix XSS vulnerability |
+
+### Commit Type to Changelog Mapping
+
+| Commit Type | Changelog Category | Notes |
+|-------------|-------------------|-------|
+| `feat` | **Added** | New features |
+| `fix` | **Fixed** | Bug fixes |
+| `perf` | **Changed** | Performance improvements |
+| `security` | **Security** | Security patches |
+| `BREAKING CHANGE` | **Changed** or **Removed** | With **BREAKING** prefix |
+| `refactor`, `docs`, `style`, `test`, `chore` | *(usually omit)* | No user impact |
+
+## Entry Format
+
+### Standard Format
+
+```markdown
+- [Action verb] [what changed] ([reference])
+```
+
+### Examples
+
+```markdown
+### Added
+- Add user dashboard with customizable widgets (#123)
+- Add support for PostgreSQL 15 (PR #456)
+
+### Changed
+- **BREAKING**: Change API response format from XML to JSON (#789)
+- Update minimum Node.js version to 18.0 (#101)
+
+### Fixed
+- Fix memory leak when processing large files (#112)
+- Fix incorrect date formatting in reports (#134)
+
+### Security
+- Fix SQL injection vulnerability in search endpoint (HIGH, CVE-2025-12345)
+```
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [Changelog Standards](../../../core/changelog-standards.md)
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format files for reduced token usage:
+- Base standard: `ai/standards/changelog.ai.yaml`
+
+## Writing Guidelines
+
+### Write for Users, Not Developers
+
+| ✅ Good | ❌ Bad | Why |
+|---------|--------|-----|
+| Add dark mode theme option | Implement ThemeProvider with context | User-facing benefit |
+| Fix login timeout on slow networks | Fix race condition in AuthService | Impact description |
+| Improve page load speed by 40% | Optimize SQL queries with indexes | Measurable outcome |
+
+### Breaking Changes
+
+Always mark breaking changes clearly:
+
+```markdown
+### Changed
+- **BREAKING**: Remove deprecated `getUserById()` method, use `getUser()` instead
+- **BREAKING**: Change configuration file format from YAML to TOML
+
+### Removed
+- **BREAKING**: Remove support for Node.js 14
+```
+
+### Security Advisories
+
+Include severity and CVE if available:
+
+```markdown
+### Security
+- Fix SQL injection vulnerability in search endpoint (HIGH, CVE-2025-12345)
+- Fix XSS vulnerability in comment rendering (MEDIUM)
+- Update dependency `lodash` to patch prototype pollution (LOW)
+```
+
+## Version Header Format
+
+```markdown
+## [VERSION] - YYYY-MM-DD
+```
+
+Examples:
+```markdown
+## [2.0.0] - 2025-12-15
+## [1.5.0-beta.1] - 2025-12-01
+## [Unreleased]
+```
+
+## Exclusion Rules
+
+The following should **NOT** be recorded in CHANGELOG:
+
+| Category | Examples | Reason |
+|----------|----------|--------|
+| Build outputs | `dist/`, `build/` | Generated files |
+| Dependencies | `node_modules/`, lock files | Auto-managed |
+| Local config | `.env`, `*.local.json` | Environment-specific |
+| IDE settings | `.vscode/`, `.idea/` | Developer preference |
+| Internal refactoring | Code style, variable names | No user impact |
+
+## Common Mistakes
+
+| ❌ Mistake | ✅ Correct |
+|-----------|-----------|
+| No dates | Include dates in ISO format |
+| Missing version links | Add comparison links at bottom |
+| Internal jargon | Use user-friendly language |
+| Too technical | Focus on user impact |
+| No categories | Use standard categories |
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check for existing `CHANGELOG.md` format
+2. Check `CONTRIBUTING.md` for changelog guidelines
+3. If not found, **default to Keep a Changelog format**
+
+### First-Time Setup
+
+If no CHANGELOG.md exists:
+
+1. Suggest creating one with the standard template
+2. Suggest documenting guidelines in `CONTRIBUTING.md`:
+
+```markdown
+## Changelog Guidelines
+
+- Update CHANGELOG.md for all user-facing changes
+- Add entries to [Unreleased] section during development
+- Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security
+- Reference issue/PR numbers: `Fix bug (#123)`
+- Mark breaking changes with **BREAKING** prefix
+```
+
+---
+
+## Related Standards
+
+- [Changelog Standards](../../../core/changelog-standards.md)
+- [Versioning Standard](../../../core/versioning.md)
+- [Commit Message Guide](../../../core/commit-message-guide.md)
+- [Release Standards Skill](../release-standards/SKILL.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-30 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)