---

name: quality-reflective-questions description: | Provides reflective questioning framework to challenge assumptions about work completeness, catching incomplete implementations before they're marked "done". Use before claiming features complete, before moving ADRs to completed status, during self-review, or when declaring work finished. Triggers on "is this really done", "self-review my work", "challenge my assumptions", "verify completeness", or proactively before marking tasks complete. Works with any type of implementation work. Enforces critical thinking about integration, testing, and execution proof.

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

1. 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?"

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

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

4. Category-Specific Questions

For New Modules/Files

Questions to ask:

1. "Where is this module imported in production code?"

   • ✅ Good: "builder.py line 45"
   • ❌ Bad: "It's imported" (where?)

2. "Are any functions from this module called?"

   • ✅ Good: "create_review_node() called in builder.py line 146"
   • ❌ Bad: "Yes, they're called" (where?)

3. "If I grep for this module in src/, do I see imports outside of tests?"

   • ✅ Good: "Yes, see: grep -r 'architecture_nodes' src/ | grep -v test"
   • ❌ Bad: "I think so" (prove it)

Red Flags:

• Module only imported in test files
• No call-sites found in production code
• Functions defined but never invoked

For LangGraph Nodes

Questions to ask:

1. "Is this node in builder.py's node list?"

   • ✅ Good: "Yes, line 146: graph.add_node('architecture_review', node)"
   • ❌ Bad: "It should be" (check it)

2. "What edges connect to this node?"

   • ✅ Good: "Conditional edge from 'query_claude' when should_review_architecture() is True"
   • ❌ Bad: "It's connected" (how?)

3. "Is this node in test_graph_completeness.py EXPECTED_NODES?"

   • ✅ Good: "Yes, added to list at line 270"
   • ❌ Bad: "I don't think we have that test" (create it)

Red Flags:

• Node file exists but not in builder.py
• Node added to graph but no edges connect to it
• Node not in integration test expected list

For CLI Commands

Questions to ask:

1. "Does this command show in --help output?"

   • ✅ Good: "Yes, verified with uv run app --help - shows 'my-command' description"
   • ❌ Bad: "It should" (verify it)

2. "Can you run this command right now?"

   • ✅ Good: "Yes: uv run app my-command arg → Output: success"
   • ❌ Bad: "Probably" (try it)

3. "Where is this command registered?"

   • ✅ Good: "main.py line 12: app.add_command(my_command)"
   • ❌ Bad: "In the CLI file" (which file? which line?)

Red Flags:

• Command function exists but not registered
• Command not in --help output
• Command causes errors when invoked

For Service Classes (with DI)

Questions to ask:

1. "Where is this service registered in the container?"

   • ✅ Good: "container.py line 67: container.register(MyService)"
   • ❌ Bad: "It's registered" (where?)

2. "Can you resolve this service from the container?"

   • ✅ Good: "Yes: container.resolve('MyService') returns instance"
   • ❌ Bad: "It should work" (try it)

3. "Where is this service injected and used?"

   • ✅ Good: "CoordinatorService line 34: def init(self, my_service: MyService)"
   • ❌ Bad: "In a few places" (which places?)

Red Flags:

• Service class exists but not registered
• Service registered but never injected
• Service injected but methods never called

For API Endpoints

Questions to ask:

1. "Where is this route registered?"

   • ✅ Good: "router.py line 23: router.add_route('/endpoint', handler)"
   • ❌ Bad: "In the routes file" (which file? which line?)

2. "Can you curl this endpoint right now?"

   • ✅ Good: "Yes: curl http://localhost:8000/api/endpoint → HTTP 200"
   • ❌ Bad: "If the server is running" (start it and try)

3. "What does this endpoint return?"

   • ✅ Good: "JSON: {'status': 'success', 'data': {...}}"
   • ❌ Bad: "The expected response" (show me the actual response)

Red Flags:

• Endpoint function exists but not registered
• Endpoint returns 404 when called
• Endpoint returns errors or unexpected responses

5. 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 tests

4. "Am I relying on 'should' or 'probably' language?"

   • If YES: You're guessing, not verifying
   • Action: Replace guesses with evidence

5. "Could this code exist and never execute?"

   • If YES: It might be orphaned
   • Action: Verify call-sites exist in production code

Execution Red Flags

1. "Have I not actually triggered this feature?"

   • If YES: You don't know if it works
   • Action: Trigger it, observe execution

2. "Am I claiming it works based on 'no errors' vs positive proof?"

   • If YES: Absence of errors ≠ presence of success
   • Action: Show positive evidence of correct behavior

3. "Did I forget to check logs after running?"

   • If YES: No execution proof
   • Action: Run again, capture logs

4. "Am I trusting tests alone without manual verification?"

   • If YES: Tests might be mocked/isolated
   • Action: Manual E2E test, verify in real environment

5. "Could this feature be wired but the conditional never triggers?"

   • If YES: Dead code path
   • Action: Verify the condition is reachable

Completion Red Flags

1. "Am I rushing to mark this complete?"

   • If YES: Slow down, verify properly
   • Action: Run through Four Questions again

2. "Do I have doubts I'm ignoring?"

   • If YES: Your instinct is usually right
   • Action: Investigate the doubt before proceeding

3. "Would I bet $1000 this works end-to-end?"

   • If NO: You're not confident
   • Action: Find out why, verify until confident

4. "Could someone else verify this works without asking me?"

   • If NO: Insufficient documentation/evidence
   • Action: Document entry point, provide evidence

5. "Am I self-approving without external review?"

   • If YES: You might miss blind spots
   • Action: Request reviewer agent or peer review

6. The Honesty Checklist

Before marking ANYTHING complete, answer these honestly:

Evidence Requirements

• I can paste the exact command to trigger this feature (Not "run the system" - the EXACT command with args)

• I can show the file and line number where this is imported/registered (Not "it's in builder.py" - the EXACT line number)

• I have actual logs showing this code executed (Not "it should log" - actual timestamped log lines)

• I can show the specific output/state change this produced (Not "it works" - the EXACT output/data)

• I triggered this manually and observed it work (Not "tests pass" - I personally ran it)

Integration Requirements

• This code is imported in at least one production file (grep output shows import, not just tests)

• This code has call-sites in production paths (grep output shows calls, not just definitions)

• This code is registered/wired where it needs to be (container, graph, router, CLI - verified)

• Integration tests verify this component is in the system (Not just unit tests - integration/E2E tests exist)

Outcome Requirements

• I can demonstrate this works to someone else right now (Could walk someone through triggering and observing)

• The behavior matches the specification (Not just "no errors" - correct behavior observed)

• I would bet money this works end-to-end (Confident enough to stake reputation on it)

• I have answered all Four Questions with specific details (No vague answers, all concrete)

If ANY checkbox is unchecked: NOT COMPLETE

7. Common Self-Deception Patterns

Pattern 1: "Tests Pass" Syndrome

Symptom: Claiming complete because unit tests pass

Reality Check:

• "Do the tests import production code or mock it?"
• "Do the tests verify integration or isolated behavior?"
• "Could code exist, tests pass, feature not work?"

Fix: Add integration tests, verify in real system

Pattern 2: "Should Work" Fallacy

Symptom: Using words like "should", "probably", "I think"

Reality Check:

• "Replace 'should' with 'does' - can you still claim it?"
• "What EVIDENCE do you have, not assumptions?"

Fix: Verify explicitly, replace assumptions with proof

Pattern 3: "No Errors" Confusion

Symptom: Equating "no errors" with "works correctly"

Reality Check:

• "Could this produce no errors but wrong output?"
• "What positive proof do you have of correct behavior?"

Fix: Show correct output, not just absence of errors

Pattern 4: "File Exists" Completion

Symptom: Marking done when artifact created, not integrated

Reality Check:

• "Is this file imported anywhere?"
• "Are these functions called anywhere?"
• "Could I delete this and nothing breaks?"

Fix: Verify imports, call-sites, integration points

Pattern 5: "Looks Good" Approval

Symptom: Vague assessment instead of specific verification

Reality Check:

• "What SPECIFIC evidence supports 'looks good'?"
• "Could you list 5 concrete verification points?"

Fix: Replace vague approval with specific checklist

Pattern 6: "I Remember Doing It" Assumption

Symptom: Trusting memory instead of current verification

Reality Check:

• "Can you show me RIGHT NOW where this is?"
• "What if your memory is wrong?"

Fix: Verify current state, don't trust memory

Pattern 7: "Later Will Be Fine" Deferral

Symptom: Skipping verification steps to finish faster

Reality Check:

• "What makes you think later is better than now?"
• "What's the cost if this is wrong and you mark it done?"

Fix: Verify now, don't defer to "later"

8. Supporting Files

References

• references/four-questions-framework.md - Deep dive into the Four Questions
• references/self-deception-patterns.md - Psychology of incomplete work
• references/honesty-in-engineering.md - Cultural aspects of honest self-assessment

Examples

• examples/good-vs-bad-answers.md - Specific vs vague answers comparison
• examples/integration-verification-dialogue.md - Sample self-questioning session

Templates

• templates/self-review-checklist.md - Copy-paste checklist for self-review
• templates/four-questions-template.md - Template for answering the Four Questions

9. Expected Outcomes

Successful Self-Review

CopyReflective Questions Self-Review
Feature: ArchitectureReview Node
Date: 2025-12-07

FOUR MANDATORY QUESTIONS:

1. How do I trigger this?
   ✅ SPECIFIC: uv run temet-run -a talky -p "Write a function"
   When should_review_architecture() returns True (when code_changes detected)

2. What connects it to the system?
   ✅ SPECIFIC: builder.py line 12: from .architecture_nodes import create_architecture_review_node
   builder.py line 146: graph.add_node("architecture_review", review_node)
   builder.py line 189: Conditional edge from "query_claude"

3. What evidence proves it runs?
   ✅ SPECIFIC: Logs from execution at 2025-12-07 10:30:45:
   [INFO] architecture_review_triggered agent=talky session=abc123
   [INFO] architecture_review_complete status=approved violations=0

4. What shows it works correctly?
   ✅ SPECIFIC: state.architecture_review = ArchitectureReviewResult(
       status=ReviewStatus.APPROVED,
       violations=[],
       recommendations=["Code follows Clean Architecture"]
   )

HONESTY CHECKLIST:
✅ All evidence specific, not vague
✅ All connections verified with grep
✅ Execution observed directly
✅ Outcome matches specification

SELF-DECEPTION CHECK:
✅ Not relying on "tests pass" alone
✅ Not using "should" or "probably"
✅ Not assuming - all verified
✅ Would bet $1000 this works

DECISION: ✅ WORK IS COMPLETE
Ready to mark as done.

Failed Self-Review (Catches Incompleteness)

CopyReflective Questions Self-Review
Feature: ArchitectureReview Node
Date: 2025-12-05 (BEFORE FIX)

FOUR MANDATORY QUESTIONS:

1. How do I trigger this?
   ⚠️  VAGUE: "Run the coordinator"
   FOLLOW-UP: What's the EXACT command?
   RE-ANSWER: uv run temet-run -a talky -p "..."
   ⚠️  STILL VAGUE: What prompts trigger the node?

2. What connects it to the system?
   ❌ VAGUE: "It should be in builder.py"
   FOLLOW-UP: Can you show me the line number?
   RE-CHECK: grep "architecture_nodes" builder.py
   RESULT: (empty) ❌
   CRITICAL: MODULE IS NOT IMPORTED

3. What evidence proves it runs?
   ❌ ASSUMPTION: "Tests pass so it should run"
   FOLLOW-UP: Have you actually run it and seen logs?
   RE-ANSWER: "No, just ran unit tests"
   CRITICAL: NO EXECUTION PROOF

4. What shows it works correctly?
   ❌ ASSUMPTION: "Tests verify behavior"
   FOLLOW-UP: What actual output did you observe?
   RE-ANSWER: "Just the test assertions passing"
   CRITICAL: NO RUNTIME OUTCOME PROOF

HONESTY CHECKLIST:
❌ Using vague language ("should", "I think")
❌ No specific line numbers or imports shown
❌ No execution logs captured
❌ Relying on tests, not runtime verification

SELF-DECEPTION CHECK:
❌ Relying on "tests pass" only
❌ Using "should" repeatedly
❌ Assuming instead of verifying
❌ Would NOT bet $1000 (honest answer: no)

DECISION: ❌ WORK IS NOT COMPLETE
Critical issues found:
1. Module not imported in builder.py
2. No runtime execution proof
3. No integration test

DO NOT mark as done. Fix integration first.

10. Requirements

Tools Required

• None (this is a mental framework)

Knowledge Required

• Understanding of what "done" means in your domain
• Willingness to be honest with yourself
• Ability to distinguish vague from specific answers

Mindset Required

• Intellectual honesty - Admit when you don't know
• Rigor - Don't accept vague answers from yourself
• Patience - Take time to verify properly
• Courage - Admit incompleteness vs rushing to "done"

11. Red Flags to Avoid

Do Not

• ❌ Accept vague answers from yourself
• ❌ Use "should", "probably", "I think" language
• ❌ Rush through questions to mark done faster
• ❌ Skip questions that feel uncomfortable
• ❌ Trust memory instead of current verification
• ❌ Assume connection without grep proof
• ❌ Claim execution without logs
• ❌ Rely on unit tests alone for integration work

Do

• ✅ Answer all Four Questions with specific details
• ✅ Replace assumptions with evidence
• ✅ Be honest about gaps and uncertainties
• ✅ Verify current state, don't trust memory
• ✅ Show concrete proof (line numbers, logs, output)
• ✅ Admit incompleteness when found
• ✅ Fix gaps before marking complete
• ✅ Use this framework for EVERY completion claim

Notes

• This skill was created in response to ADR-013 (2025-12-07)
• The pattern: Self-deception about completeness led to orphaned code
• This skill provides the mental framework BEFORE technical verification
• Pair this with quality-verify-implementation-complete for full coverage
• The Four Questions are the MINIMUM bar, not the complete verification
• Honesty with yourself is the foundation of quality work

Remember: The person you're most likely to deceive is yourself. These questions force honesty.