quality-reflective-questions

What this skill does

# Reflective Questions for Work Completeness

## Quick Start

Before marking ANYTHING as "done", ask yourself these questions and provide HONEST answers:

### The Four Mandatory Questions

1. **How do I trigger this?** (What's the entry point?)
2. **What connects it to the system?** (Where's the wiring?)
3. **What evidence proves it runs?** (Show me the logs)
4. **What shows it works correctly?** (What's the outcome?)

If you **cannot answer ALL FOUR** with specific, concrete details, **the work is NOT complete**.

### The Honesty Test

Replace vague answers with specific evidence:

❌ **Bad (vague):** "It's integrated" → ✅ **Good (specific):** "Imported in builder.py line 45"
❌ **Bad (vague):** "It works" → ✅ **Good (specific):** "Logs show execution at 10:30:45"
❌ **Bad (vague):** "Tests pass" → ✅ **Good (specific):** "46 unit tests + 2 integration tests pass"

## Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. The Four Mandatory Questions (Deep Dive)
4. Category-Specific Questions
5. Red Flag Questions
6. The Honesty Checklist
7. Common Self-Deception Patterns
8. Supporting Files
9. Expected Outcomes
10. Requirements
11. Red Flags to Avoid

## When to Use This Skill

### Explicit Triggers
- "Challenge my assumptions about completeness"
- "Ask me reflective questions about my work"
- "Self-review my implementation"
- "Is this really done?"
- "Verify my work is complete"
- "Question my completion claims"

### Implicit Triggers (PROACTIVE)
- **Before marking any task complete** (every single time)
- **Before moving ADR from in_progress to completed**
- **Before claiming "feature works"**
- **Before self-approving work**
- **After implementing any feature**
- **When about to say "all tests passing ✅"**

### Debugging Triggers
- "Why do I feel uncertain about this?"
- "Something seems incomplete but I can't pinpoint it"
- "I want to mark this done but have doubts"
- "Am I missing something?"

## What This Skill Does

This skill provides a **structured framework of reflective questions** that:

1. **Challenges assumptions** about what "done" means
2. **Exposes gaps** between claimed completion and actual completion
3. **Forces specificity** instead of vague assurances
4. **Prevents premature completion** by requiring evidence
5. **Catches integration failures** before they become incidents

**This skill complements `quality-verify-implementation-complete`** by providing the mental framework for self-questioning BEFORE running technical verification.

## The Four Mandatory Questions (Deep Dive)

These questions MUST be answered for EVERY piece of work before claiming "done".

### Question 1: How do I trigger this?

**Purpose:** Verify the feature has a reachable entry point

**What it really asks:**
- Can a user/system actually invoke this code?
- Is there a documented way to make this execute?
- Could someone else trigger this without asking me?

**Good Answers (Specific):**
- ✅ "Run: `uv run temet-run -a talky -p 'analyze code'`"
- ✅ "Call: `curl -X POST /api/endpoint -d '{...}'`"
- ✅ "Import: `from myapp import MyService; MyService().method()`"
- ✅ "Event: Coordinator triggers when `should_review_architecture()` returns True"

**Bad Answers (Vague):**
- ❌ "Run the system"
- ❌ "It's automatic"
- ❌ "The coordinator calls it"
- ❌ "When needed"

**Follow-up Questions:**
- "Can you show me the EXACT command right now?"
- "What arguments/parameters are required?"
- "Under what conditions does this trigger?"
- "Could you trigger this in the next 30 seconds if asked?"

**If you cannot answer specifically:** The feature has no entry point → NOT COMPLETE

### Question 2: What connects it to the system?

**Purpose:** Verify the artifact is actually wired into the codebase

**What it really asks:**
- Where is the import statement?
- Where is the registration/initialization?
- Where is the configuration that enables this?
- Can you show me the LINE NUMBER where this is connected?

**Good Answers (Specific):**
- ✅ "builder.py line 45: `from .architecture_nodes import create_review_node`"
- ✅ "main.py line 12: `app.add_command(my_command)`"
- ✅ "container.py line 67: `container.register(MyService, scope=Scope.SINGLETON)`"
- ✅ "routes.py line 23: `router.add_route('/endpoint', handler)`"

**Bad Answers (Vague):**
- ❌ "It's imported"
- ❌ "It's in the builder"
- ❌ "It's registered"
- ❌ "It's wired up"

**Follow-up Questions:**
- "Can you paste the EXACT import line?"
- "What FILE and LINE NUMBER has the registration?"
- "Can you show me with grep output?"
- "Could I find this connection in 60 seconds if I looked?"

**If you cannot answer specifically:** The artifact is orphaned → NOT COMPLETE

### Question 3: What evidence proves it runs?

**Purpose:** Verify the code actually executes at runtime

**What it really asks:**
- Have you ACTUALLY triggered this and observed execution?
- What logs/traces show this code path was hit?
- Can you show me timestamped evidence of execution?
- Did you observe this with your own eyes (or grep)?

**Good Answers (Specific):**
- ✅ "Logs: `[2025-12-07 10:30:45] INFO architecture_review_triggered agent=talky`"
- ✅ "Output: `✓ Task completed successfully` (from CLI run at 10:30)"
- ✅ "Trace: OpenTelemetry span `architecture_review` with duration 1.2s"
- ✅ "Debug: Added print statement, saw output 'Node executed'"

**Bad Answers (Vague):**
- ❌ "It should run"
- ❌ "Tests pass"
- ❌ "No errors when I ran it"
- ❌ "The system works"

**Follow-up Questions:**
- "Can you paste the ACTUAL log line showing execution?"
- "What TIMESTAMP did this execute?"
- "Did you observe this directly or are you assuming?"
- "Could you trigger this RIGHT NOW and show me the logs?"

**If you cannot answer specifically:** No execution proof → NOT COMPLETE

### Question 4: What shows it works correctly?

**Purpose:** Verify the code produces the expected outcome

**What it really asks:**
- What observable outcome proves correct behavior?
- What state changed as a result of execution?
- What output/artifact was created?
- How do you KNOW it did the right thing?

**Good Answers (Specific):**
- ✅ "State: `result.architecture_review = ArchitectureReviewResult(status=APPROVED, violations=[])`"
- ✅ "Database: Row inserted with ID 123, verified with query"
- ✅ "File: Created `output.txt` with expected contents (see: cat output.txt)"
- ✅ "API: Returned HTTP 200 with JSON body containing expected fields"

**Bad Answers (Vague):**
- ❌ "It works"
- ❌ "No errors"
- ❌ "Tests pass"
- ❌ "Everything looks good"

**Follow-up Questions:**
- "Can you show me the EXACT output/state change?"
- "What VALUE did this produce?"
- "How do you KNOW this is correct vs just 'no errors'?"
- "Could you demonstrate correct behavior RIGHT NOW?"

**If you cannot answer specifically:** No outcome proof → NOT COMPLETE

## Category-Specific Questions

Apply the Four Questions framework to specific implementation types. For detailed questions by category, see [references/category-specific-questions.md](./references/category-specific-questions.md).

**Categories covered:**
- **Modules/Files**: Import verification, call-site validation
- **LangGraph Nodes**: Graph registration, edge connectivity
- **CLI Commands**: Registration, --help visibility, execution
- **Service Classes (DI)**: Container registration, injection points
- **API Endpoints**: Route registration, response validation

## Red Flag Questions

These questions expose common self-deception patterns. If you answer "yes" to any, **stop and investigate**.

### Integration Red Flags

1. **"Did I only test this in isolation?"**
   - If YES: You might have orphaned code
   - Action: Add integration test, verify in real system

2. **"Am I assuming something is connected without verifying?"**
   - If YES: Assumption might be wrong
   - Action: Grep for imports, verify connection exists

3. **"Did I only run unit tests, not integration tests?"**
   - If YES: Integration might be broken
   - Action: Create/run integration test