# Workflow Prerequisite Checking / 工作流前置步驟檢查

**Version**: 1.0.0
**Last Updated**: 2026-02-12

---

## Overview

This document defines how AI assistants should check prerequisites before executing slash commands. It ensures users follow recommended workflow sequences while preserving flexibility for experienced users.

本文件定義 AI 助手在執行斜線命令前如何檢查前置條件。確保使用者遵循建議的工作流序列，同時保留資深使用者的彈性。

---

## Algorithm / 演算法

When a slash command is invoked:

1. **Look up command** in `methodologies/workflow-prerequisites.yaml`
2. **If `entry_point: true`** → Proceed immediately
   - If `recommended_prior` is defined → Briefly mention recommended prior steps
3. **If `entry_point: false`** → Check `requires_artifact`:
   a. Scan conversation context for evidence of artifact completion
   b. If artifact evidence found → Proceed
   c. If artifact NOT found → Prompt user with options
4. **Never block** — always offer "continue anyway" option

---

## Evidence Detection / 證據偵測

When checking for required artifacts, scan the current conversation for these signals:

| Artifact | Evidence Signals | 證據信號 |
|----------|-----------------|----------|
| `spec-approved` | SPEC-XXX.md mentioned with "approved" / "核准" state; or user references an existing spec file | 對話中提及 SPEC 文件且已核准 |
| `derived-tests` | `.feature` or `.test.ts` files recently generated by `/derive` | 最近由 /derive 產生的測試檔案 |
| `passing-tests` | Test run output with all passing | 測試全數通過的輸出 |
| `discovery-report` | `/discover` output present in conversation | 對話中有 /discover 的輸出 |
| `reverse-spec` | `/reverse spec` output present in conversation | 對話中有 /reverse spec 的輸出 |
| `changelog-updated` | CHANGELOG.md modification mentioned or committed | 對話中提及 CHANGELOG.md 已更新 |
| `feature-files` | `.feature` files from `/bdd` in conversation | 對話中有 /bdd 產生的 .feature 檔案 |
| `acceptance-criteria` | ATDD table or AC definitions in conversation | 對話中有 ATDD 表格或 AC 定義 |
| `ideation-output` | `/brainstorm` output present in conversation | 對話中有 /brainstorm 的輸出 |
| `user-story` | User story with AC in conversation | 對話中有使用者故事和 AC |

---

## User Prompt Templates / 使用者提示模板

### Hard Prerequisites Not Met (requires_artifact)

**Chinese (Primary):**

```
⚠️ `/[command]` 通常需要先完成以下步驟：
- [ ] [prerequisite description]

您想要：
1. 先執行 `/[prerequisite-command]`（建議）
2. 直接繼續（跳過前置步驟）
```

**English:**

```
⚠️ `/[command]` typically requires these prior steps:
- [ ] [prerequisite description]

Would you like to:
1. Run `/[prerequisite-command]` first (recommended)
2. Continue anyway (skip prerequisites)
```

### Soft Prerequisites (recommended_prior)

**Chinese (Primary):**

```
💡 小提示：執行 `/[recommended-command]` 可以提供更好的脈絡。
   繼續執行 `/[command]`...
```

**English:**

```
💡 Tip: Running `/[recommended-command]` first can provide better context.
   Continuing with `/[command]`...
```

---

## Soft vs Hard Prerequisites / 軟性 vs 硬性前置

| Type | Field | Behavior | Example |
|------|-------|----------|---------|
| **Hard** | `requires_artifact` | Cannot produce meaningful output without it; strong recommendation to complete first | `/derive` without approved SPEC |
| **Soft** | `recommended_prior` | Better results with it, but not required; brief mention, proceed by default | `/sdd` without `/discover` |

### Hard Prerequisite Examples

| Command | Missing Artifact | Prompt |
|---------|-----------------|--------|
| `/derive` | `spec-approved` | "⚠️ `/derive` 需要一份已核准的 SPEC 文件。建議先執行 `/sdd` 建立規格。" |
| `/release` | `changelog-updated` | "⚠️ `/release` 需要先更新 CHANGELOG.md。建議先執行 `/release changelog`。" |
| `/bdd-review` | `derived-tests` | "⚠️ `/bdd-review` 需要從 `/derive` 產生的測試檔案。" |

### Soft Prerequisite Examples

| Command | Recommended Prior | Prompt |
|---------|------------------|--------|
| `/sdd` | `discover` | "💡 小提示：先執行 `/discover` 可以提供專案脈絡。繼續執行 `/sdd`..." |
| `/reverse` | `discover` | "💡 小提示：先執行 `/discover` 可以了解專案全貌。繼續執行 `/reverse`..." |
| `/refactor` | `discover` | "💡 小提示：先執行 `/discover` 可以識別重構熱點。繼續執行 `/refactor`..." |

---

## Integration with Methodology Sessions / 與方法論會話的整合

- If user is in an **active methodology session** (e.g., TDD cycle), use the methodology's phase sequence as the primary prerequisite source
- If **no active methodology**, use `workflow-prerequisites.yaml` as fallback
- If **multiple workflows** contain the command, only ONE workflow needs to be satisfied

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-02-12 | Initial prerequisite checking specification |
