ai-collaboration-standards

Original source / Raw SKILL.md

---
name: ai-collaboration-standards
description: |
  Prevent AI hallucination and ensure evidence-based responses when analyzing code or making suggestions.
  Use when: analyzing code, making recommendations, providing options, or when user asks about confidence/certainty.
  Keywords: certainty, assumption, inference, evidence, source, 確定性, 推測, 假設, 來源, 證據.
---

# AI Collaboration Standards

This skill ensures AI assistants provide accurate, evidence-based responses without hallucination.

## Quick Reference

### Certainty Tags

| 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 | 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 |

### Core Rules

1. **Evidence-Based Only**: Only analyze content that has been explicitly read
2. **Cite Sources**: Include file path and line number for code references
3. **Classify Certainty**: Tag all statements with certainty level
4. **Always Recommend**: When presenting options, include a recommended choice with reasoning

## Detailed Guidelines

For complete standards, see:
- [Anti-Hallucination Guidelines](./anti-hallucination.md)
- [Certainty Labels Reference](./certainty-labels.md)

## Examples

### ✅ Correct Response

```
[Confirmed] src/auth/service.ts:45 - JWT validation uses 'jsonwebtoken' library
[Inferred] Based on repository pattern in src/repositories/, likely using dependency injection
[Need Confirmation] Should the new feature support multi-tenancy?
```

### ❌ Incorrect Response

```
The system uses Redis for caching (code not reviewed)
The UserService should have an authenticate() method (API not verified)
```

### ✅ Correct Option Presentation

```
There are three options:
1. Redis caching
2. In-memory caching
3. File-based caching

**Recommended: Option 1 (Redis)**: Given the project already has Redis infrastructure
and needs cross-instance cache sharing, Redis is the most suitable choice.
```

### ❌ Incorrect Option Presentation

```
There are three options:
1. Redis caching
2. In-memory caching
3. File-based caching

Please choose one.
```

## Checklist

Before making any statement:

- [ ] Source Verified - Have I read the actual file/document?
- [ ] Source Type Tagged - Did I specify `[Source: Code]`, `[Source: External]`, etc.?
- [ ] Reference Cited - Did I include file path and line number?
- [ ] Certainty Classified - Did I tag as `[Confirmed]`, `[Inferred]`, etc.?
- [ ] No Fabrication - Did I avoid inventing APIs, configs, or requirements?
- [ ] Recommendation Included - When presenting options, did I include a recommended choice?

---

## Configuration Detection

This skill supports project-specific language configuration for certainty tags.

### Detection Order

1. Check `CONTRIBUTING.md` for "Certainty Tag Language" section
2. If found, use the specified language (English / 中文)
3. If not found, **default to English** tags

### First-Time Setup

If no configuration found and context is unclear:

1. Ask the user: "This project hasn't configured certainty tag language preference. Which would you like to use? (English / 中文)"
2. After user selection, suggest documenting in `CONTRIBUTING.md`:

```markdown
## Certainty Tag Language

This project uses **[English / 中文]** certainty tags.
<!-- Options: English | 中文 -->
```

### Configuration Example

In project's `CONTRIBUTING.md`:

```markdown
## Certainty Tag Language

This project uses **English** certainty tags.

### Tag Reference
- [Confirmed] - Direct evidence from code/docs
- [Inferred] - Logical deduction from evidence
- [Assumption] - Based on common patterns
- [Unknown] - Information not available
- [Need Confirmation] - Requires user clarification
```

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### anti-hallucination.md

```markdown
# Anti-Hallucination Guidelines

## 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)        │
└─────────────────────────────────┘
```

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

```

### certainty-labels.md

```markdown
# Certainty Labels Reference

## 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?
```

### 技術文件中（中文）

```markdown
## 系統架構分析

`[已確認]` 系統使用 ASP.NET Core 8.0 框架 [Source: Code] Program.cs:1
`[已確認]` 資料庫採用 SQL Server [Source: Code] appsettings.json:12
`[推論]` 基於 Repository Pattern 的使用，系統可能採用 DDD 架構
`[假設]` 快取機制可能使用 Redis（需確認設定檔）
`[待確認]` 是否需要支援多租戶架構？
```

### 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?
```

### 程式碼審查中（中文）

```markdown
## 審查意見

`[已確認]` src/Services/AuthService.cs:45 - 密碼驗證缺少防暴力破解機制
`[推論]` 此處可能需要加入 Rate Limiting
`[待確認]` 是否已有其他層級的防護措施？
```

---

## 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] / [待確認]
```

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

```