# Step 01.6.8: Technical Limitations Detection

**Purpose:** Detect and surface `## Technical Limitations` entries from the story file during pre-flight, displaying `decision: pending` entries as prominent attention items and resolved entries as informational context.
**Behavior:** Purely informational — does not block workflow progression, no error on absence. Silently completes when section is absent.

---

## Detection Logic

After the story file is loaded into context (Step 01.6), scan for the Technical Limitations section:

### Scan for `## Technical Limitations` Section

```
tl_section = Grep(pattern="## Technical Limitations", path=story_file)
```

If the section is absent or not found, silently set counts to zero and skip all output — no warnings, no errors, no display.

### Parse `technical_limitations` YAML Block

If the section exists, locate and parse the fenced YAML code block containing the `technical_limitations` key:

```
Read(file_path=story_file)
# Extract YAML block between ``` markers within ## Technical Limitations section
# Parse the technical_limitations array entries
```

Each entry in the `technical_limitations` YAML array has these fields:
- `id` — Unique identifier (e.g., TL-001)
- `component` — The affected component
- `limitation` — Description of the technical limitation
- `decision` — Resolution status (pending, accepted, defer, descope, workaround)
- `discovered_phase` — When the limitation was discovered
- `impact` — Severity and scope of the limitation

### Template Placeholder Detection

Before processing entries, check for template placeholder text containing square bracket delimiters (e.g., `[placeholder text]`). If an entry's component or limitation field contains square bracket placeholder text, skip that entry silently — do not count it, do not display it. This prevents false positives from unfilled story template fields.

---

## Display Logic

Initialize counters:
```
TECH_LIMITATIONS_COUNT = 0
PENDING_DECISIONS_COUNT = 0
```

### Processing Each Entry

Count each entry individually toward TECH_LIMITATIONS_COUNT, including entries with duplicate TL IDs. Each entry is counted regardless of whether its id has appeared before.

For each valid (non-placeholder) entry in the technical_limitations array:

```
TECH_LIMITATIONS_COUNT += 1

IF entry.decision starts with "pending" OR entry.decision == "pending":
    PENDING_DECISIONS_COUNT += 1
    Display with ATTENTION formatting (see Pending Decision Display below)
ELSE:
    Display with informational formatting (see Resolved Entry Display below)
```

### Pending Decision Display (ATTENTION Formatting)

For entries where the decision is pending:

```
Display: "⚠️ ATTENTION: Pending technical decision"
Display: "  Component: {entry.component}"
Display: "  Limitation: {entry.limitation}"
Display: "  Impact: {entry.impact}"
Display: "  Discovered: {entry.discovered_phase}"
```

### Resolved Entry Display (Informational)

For resolved entries (decision is not pending — e.g., accepted, defer, descope, workaround), display a compact informational line. Resolved entries contribute to TECH_LIMITATIONS_COUNT but not to PENDING_DECISIONS_COUNT:

```
Display: "  TL-{entry.id}: {entry.component} — {entry.decision}"
```

Note: Decision values may contain colons (e.g., `accepted:backtick-only-support`). The full decision value including any colons should be displayed as-is without truncation at the colon character.

### Summary Line

After processing all entries:

```
Display: "Technical Limitations: {TECH_LIMITATIONS_COUNT} total, {PENDING_DECISIONS_COUNT} pending"
```

---

## Absent Section Handling

When the story file does not contain a `## Technical Limitations` section (e.g., pre-v2.8 format stories or stories where the section was removed):

- Set TECH_LIMITATIONS_COUNT = 0
- Set PENDING_DECISIONS_COUNT = 0
- Produce no output — silently complete with no display, no warning, no error
- The step completes as if it was never invoked when the section is absent

This ensures 100% backward compatibility with older story formats.

---

## Malformed YAML Handling

When the Technical Limitations section exists but the YAML block is malformed, contains invalid syntax, has missing required fields, or is an empty block:

- Display a warning: "Warning: Could not parse Technical Limitations YAML — malformed or invalid YAML detected"
- Set TECH_LIMITATIONS_COUNT = 0 (error results in zero counts)
- Set PENDING_DECISIONS_COUNT = 0 (error results in zero counts)
- Continue workflow — degrade gracefully with best-effort recovery
- Do NOT block or stop the pre-flight process

The step uses a best-effort approach: recover from parse errors by setting zero counts and warning, then proceed normally.

---

## Variable Output

| Variable | Type | Description |
|----------|------|-------------|
| `$TECH_LIMITATIONS_COUNT` | Integer | Total number of valid (non-placeholder) technical limitation entries |
| `$PENDING_DECISIONS_COUNT` | Integer | Count of entries where decision is pending |

These variables are available for downstream phases and the completion checkpoint.

---

## Edge Case Handling

| Scenario | Behavior |
|----------|----------|
| Section absent (pre-v2.8 stories) | Silent pass — no output produced, counts set to 0 |
| Empty YAML block | Warning displayed, counts set to 0 |
| Malformed YAML syntax | Warning displayed, counts set to 0, graceful recovery |
| Template placeholder text (square brackets) | Entry skipped silently, not counted |
| Decision values with colons (e.g., `accepted:backtick-only-support`) | Full value displayed as-is |
| Duplicate TL IDs | Each entry counted individually |
| All entries pending | All displayed with ATTENTION formatting |
| All entries resolved | All displayed with informational formatting |
| Mixed pending and resolved | Each formatted per its decision status |
| Unrecognized decision values | Treated as resolved (informational, not pending) |
