Canonize Product Flaws

Overview

Interview users about emergent behaviors that have become beloved or expected, and register them in a Canon of Flaws for protection against well-intentioned "optimization" that would make the product worse.

Philosophy

> "Beloved 'bugs' are registered and protected from optimization"

The key insight is that a "perfect" implementation of the original design would often be worse than the imperfect reality users have come to love. This skill protects the emergent soul of products by documenting the gap between what was intended and what users actually value.

Instructions

Pre-Flight Checks

Before beginning the interview:

1. Verify `.sigil-setup-complete` exists in the project root

2. Check if `sigil-mark/soul-binder/canon-of-flaws.yaml` exists

- If missing, create it with an empty flaws array structure

3. Load strictness level from `.sigilrc.yaml` to determine enforcement behavior

Step 1: Identify the Behavior

If the user hasn't specified a behavior name, ask:

**"What emergent behavior would you like to protect?"**

Explain what qualifies as a canonizable flaw:

Common examples:

Step 2: Interview - Intended vs Emergent

Conduct a structured interview to capture the behavioral gap:

**2.1: Intended Behavior**

Ask: "What was the INTENDED behavior? What should have happened according to the original design?"

Document the theoretical "correct" behavior that was originally designed.

**2.2: Emergent Behavior**

Ask: "What ACTUALLY happens (that became beloved)? Describe the behavior users have come to expect."

Capture the reality that users have embraced.

**2.3: Discovery**

Ask: "How did you discover this behavior was valued?"

Present options:

Step 3: Interview - Protection Criteria

Assess whether this flaw meets the threshold for protection:

**3.1: Usage**

Ask: "Approximately what percentage of users rely on this behavior?"

Options:

If usage is below 5%, warn the user but allow proceeding with `UNDER_REVIEW` status instead of `PROTECTED`.

**3.2: Community Attachment**

Ask: "How would users react if this behavior was 'fixed'?"

Options:

**3.3: Skill Expression (Optional)**

Ask: "Does this behavior reward skill or expertise?"

Options:

Step 4: Define Protection

Make the protection actionable with specific technical patterns:

**4.1: Affected Code**

Ask: "What code patterns might accidentally 'fix' this behavior?"

Provide examples of glob patterns:

Accept glob patterns that should trigger protection checks during code review.

**4.2: Protection Rule**

Ask: "Complete this sentence: 'Any change that __________ must be BLOCKED.'"

Example: "Any change that prevents the double-click animation must be BLOCKED."

Step 5: Generate Canon Entry

Read existing entries in `canon-of-flaws.yaml` to determine the next sequential flaw ID. Generate a YAML entry in this format:

```yaml

name: "{behavior_name}"

status: "PROTECTED" # or UNDER_REVIEW if usage < 5%

canonized_date: "{today's date}"

canonized_by: "{user or 'Taste Owner'}"

description: |

{Brief description of the flaw}

intended_behavior: |

{Answer from Q2.1}

emergent_behavior: |

{Answer from Q2.2}

why_protected: |

- Discovery: {From Q2.3}

- Usage: {From Q3.1}

- Attachment: {From Q3.2}

- {Additional context if provided}

affected_code_patterns:

- "{pattern_1}"

- "{pattern_2}"

protection_rule: |

{From Q4.2}

de_canonization:

requires_threshold: 70 # percent approval

cooldown_days: 180

```

Step 6: Confirm and Save

Present the generated entry to the user in a formatted, readable way.

Ask: "Does this accurately capture the behavior to protect?"

Options:

On confirmation:

1. Load the existing `canon-of-flaws.yaml` file

2. Append the new flaw to the flaws array

3. Update the `last_updated` timestamp in the file metadata

4. Write the updated file back to disk

Step 7: Report Success

Present a summary report:

```

{status_emoji} FLAW-{id} "{name}" has been added to the Canon of Flaws.

Status: {PROTECTED | UNDER_REVIEW}

The agent will now {BLOCK | WARN on} any change that matches:

{affected_patterns}

Protection Rule:

"{protection_rule}"

De-canonization process:

- Requires 70% community approval

- Requires Taste Owner sign-off

- Update canon-of-flaws.yaml status to DE_CANONIZED

Next steps:

- Code changes to affected patterns will be {blocked | flagged}

- This flaw will be respected during implementation

```

Strictness Behavior

The enforcement level depends on the project's strictness configuration:

| Strictness | Protected Flaw Violation |

|------------|--------------------------|

| discovery | Informational note only |

| guiding | Warning with explanation |

| enforcing | BLOCK with override option |

| strict | BLOCK with override option |

Error Handling

| Error | Cause | Resolution |

|-------|-------|------------|

| "Setup not complete" | Missing `.sigil-setup-complete` marker | Run setup first |

| "Usage below threshold" | < 5% usage reported | Allow with UNDER_REVIEW status |

| "Similar flaw exists" | Duplicate pattern detected | Suggest updating existing flaw |

| "Canon file missing" | No `canon-of-flaws.yaml` found | Create empty file structure |

Important Constraints

**Do NOT:**

**DO:**

Example Use Cases

1. **Beloved Animation Timing**: A loading animation that takes slightly longer than optimal but users find more trustworthy

2. **Hidden Power Features**: An undocumented keyboard shortcut combination that power users discovered and shared

3. **Quirky UI Behavior**: A button that requires a double-click due to a timing bug, but users now expect it and rely on it as confirmation

4. **Accidental Game Mechanic**: In game design, techniques like "bunny hopping" or "rocket jumping" that became core to competitive play