[syntax-error-quality] Daily Syntax Error Quality Check: 2026-03-12 – Average Score 62.7/100 ⚠️ Below Threshold #20711

workflow-generator.md:1:1: error: failed to parse frontmatter:
[14:8]: mapping value is not allowed in this context
    12 |   contents: read
    13 |   issues: read
  > 14 | engine copilot
            ^
    15 |   pull-requests: read
: failed to parse frontmatter:
[14:8]: mapping value is not allowed in this context   ← DUPLICATED
    ...
```

#### Evaluation Scores

| Dimension | Score | Rating |
|-----------|-------|--------|
| Clarity | 14/25 | Poor |
| Actionability | 8/25 | Poor |
| Context | 13/20 | Acceptable |
| Examples | 2/15 | Critical |
| Consistency | 7/15 | Poor |
| **Total** | **44/100** | **❌ Critical** |

#### Strengths
- ✅ goccy YAML error includes correct inner line number and source context with `^` pointer
- ✅ Shows problematic source line

#### Weaknesses
- ❌ Outer position is always `file:1:1` (incorrect – error is at line 14)
- ❌ Technical YAML jargon: "mapping value is not allowed in this context" – confusing to non-YAML experts
- ❌ Error message is duplicated due to `fmt.Errorf("%s: %w", formattedErr, cause)` wrapping in `compiler_error_formatter.go:32`
- ❌ Two conflicting formats in the same output: outer `file:1:1:` + inner `[14:8]:`
- ❌ No suggestion or example of correct syntax

#### Improvement Suggestions

1. **Extract accurate line/col from the goccy YAML error before wrapping**:
   ```go
   // In compiler.go, instead of:
   return formatCompilerError(markdownPath, "error", err.Error(), err)
   // Use position extracted from the YAML error:
   line, col := extractPositionFromYAMLError(err)
   return formatCompilerErrorWithPosition(markdownPath, line, col, "error", err.Error(), nil)
   ```

2. **Prevent message duplication** – pass `nil` as cause when the message already includes the error:
   ```go
   // compiler_error_formatter.go line 32: Only chain cause when it adds NEW information
   // Currently duplicates content since message = err.Error()
   ```

3. **Translate common YAML errors to plain language** in `pkg/parser/yaml_error.go`:
   - `"mapping value is not allowed in this context"` → `"Missing ':' after key (e.g., 'engine copilot' should be 'engine: copilot')"`
   - `"did not find expected key"` → `"Incorrect indentation or missing key"`

4. **Add corrective example for missing colon errors**:
   ```
   Correct syntax:
   engine: copilot
   ```

</details>

<details>
<summary><b>Test Case 2: Invalid Engine Name (cli-version-checker.md)</b> – Score: 80/100 ✅</summary>

#### Test Configuration

**Workflow**: `.github/workflows/cli-version-checker.md` (342 lines, medium)  
**Error Type**: Category B – Invalid engine name  
**Error Introduced**: `engine: copiilot` (typo – double 'i', should be `copilot`)

#### Compiler Output (reconstructed from source analysis)

Source: `pkg/workflow/engine_validation.go:235` via `validateEngine("copiilot")`

```
cli-version-checker.md:1:1: error: invalid engine: copiilot. Valid engines are: claude, codex, copilot.

Did you mean: copilot?

Example:
engine: copilot

See: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/engines.md
```

#### Evaluation Scores

| Dimension | Score | Rating |
|-----------|-------|--------|
| Clarity | 22/25 | Excellent |
| Actionability | 22/25 | Excellent |
| Context | 11/20 | Acceptable |
| Examples | 13/15 | Excellent |
| Consistency | 12/15 | Good |
| **Total** | **80/100** | **✅ Good** |

#### Strengths
- ✅ Lists all valid engines in the error message
- ✅ "Did you mean: copilot?" via Levenshtein distance fuzzy matching
- ✅ Shows correct usage example: `engine: copilot`
- ✅ Links to documentation

#### Weaknesses
- ⚠️ Position is always `file:1:1` (the engine field is not at line 1 – should detect actual line)
- ⚠️ No source code context shown (no `Context` field populated)

#### Improvement Suggestions

1. **Populate source context** – read the source file and add surrounding lines to show where `engine: copiilot` appears
2. **Use accurate line position** – detect the line where `engine:` is defined in the frontmatter

</details>

<details>
<summary><b>Test Case 3: Invalid Permissions Scope (pr-triage-agent.md)</b> – Score: 64/100 ⚠️</summary>

#### Test Configuration

**Workflow**: `.github/workflows/pr-triage-agent.md` (450 lines, complex)  
**Error Type**: Category C – Invalid configuration field  
**Error Introduced**: `permissions: { unknown-scope: read }` (invalid permission scope)

#### Compiler Output (reconstructed from source analysis)

Source: `pkg/parser/schema_errors.go:223` → `rewriteAdditionalPropertiesError()` → `formatCompilerErrorWithPosition()`

```
pr-triage-agent.md:4:3: error: Unknown property: unknown-scope
   2 | permissions:
 > 3 |   unknown-scope: read
     |   ^^^^^^^^^^^^^
   4 | ---