epic: pre-existing validation errors cleanup (3 child issues)

Overview

Post-merge validation of PR #1499 revealed several pre-existing validation errors that are not related to the infrastructure cleanup work but should be addressed for CI/CD pipeline health.

Pre-Existing Issues Found

1. Frontmatter Validation Errors (542+ errors)

Location: .github/agents/*/ directories
Issue: Missing required file_type field in agent configuration files
Files Affected:

.github/agents/ai-readiness-estimator-agent/claude/agent.md
.github/agents/client-website-discovery-assistant-agent/claude/agent.md
.github/agents/harvest-analytical-agent/claude/agent.md
.github/agents/linear-advisor-agent/claude/agent.md
.github/agents/pagespeed-agent/claude/agent.md
.github/agents/proposal-desk-agent/claude/agent.md
.github/agents/website-content-strategist-agent/claude/agent.md
.github/agents/website-scope-estimator-agent/claude/agent.md
.github/agents/zendesk-support-agent/claude/agent.md
Plus all corresponding shared/core-prompt.md files lacking frontmatter entirely

Required Fix: Add file_type: 'agent' or file_type: 'prompt' to frontmatter as per schema validation

2. Markdown Linting Errors (309 issues)

Location: projects/active/repo-restructuring-2026-07-25/DECISIONS_FRAMEWORK-50-QUESTIONS.md
Issues:

MD051: Link fragments with special characters not properly escaped (200+ instances)
MD029: Ordered list prefix numbering inconsistencies
MD012: Multiple consecutive blank lines
MD009: Trailing whitespace

Root Cause: Document has complex anchor link references that don't comply with markdown standards

3. ESLint Warnings (68 warnings)

Issue: Unused caught error variables that should follow underscore prefix convention
Pattern: catch (e) { ... } should be catch (_e) { ... } or catch (_) { ... }

Context

These issues were pre-existing and not introduced by PR #1499. The main work of that PR (ESLint violation reduction from 592→45 and footer injection) is complete and merged.

Recommendations

Priority 1: Frontmatter Fixes (Quick Win)

Add missing file_type fields to agent configuration files. Straightforward and would resolve ~200+ validation errors.

Priority 2: Markdown Linting (Medium Effort)

Fix link fragment formatting or add exceptions for the decisions framework document.

Priority 3: ESLint Warnings (Low Priority)

Rename unused catch variables with underscore prefix. Non-critical but improves code quality consistency.

Definition of Ready (DoR)

Reproduction steps clearly documented
Expected vs actual behavior defined
Environment/version information captured
Related issues/PRs linked
Severity/impact assessed
Acceptance criteria for fix defined

Definition of Done (DoD)

Bug fix verified and reproduction steps no longer apply
Root cause identified and documented
Tests added/updated to prevent regression; CI green
No new warnings or errors introduced
Docs/changelog updated
Backport considered (if applicable)
Release notes prepared

LS-2265

✅ Template check passed after update. Thanks for fixing the issue body.

⏱️ Aging and SLA annotation

Age: 8 day(s)
SLA state: SLA risk
Thresholds: warn at 7 days, breach at 14 days
Last updated: 2026-08-12T22:42:20.942Z

Maintained by project-meta-sync workflow.

Clarification

After investigation, I can confirm:

✅ These validation errors are PRE-EXISTING — not introduced by PR #1499 or Issue #1486

No changes to .github/agents/ files in our merge
No changes to DECISIONS_FRAMEWORK file in our merge
All 384 footer-injected files have proper frontmatter

Status of Main Work:

Issue Repository Infrastructure Cleanup: ESLint & Footer Validation (Housekeeping Epic) #1486: ✅ CLOSED (merged)
PR chore: fix ESLint violations and inject category-specific footers #1499: ✅ MERGED to develop
ESLint violations: ✅ FIXED (592 → 45)
Footer injection: ✅ COMPLETED (384 files)

This issue (#1507) documents technical debt for separate cleanup — NOT blockers for the infrastructure cleanup work.

Should This Issue Exist?

Options:

Keep it: Track as a formal technical debt issue for future cleanup sprints
Close it: Mark pre-existing issues as outside scope of this effort
Modify it: Reframe as a refactoring epic with lower priority

Awaiting triage decision.

Updated after validation investigation

Epic Restructure ✅

This issue has been restructured as the parent epic grouping three focused child issues for technical debt cleanup.

Child Issues (Linked Work Items)

Priority 1: Quick Win 🟢

chore: add missing file_type to agent configuration files #1510 — chore: add missing file_type to agent configuration files
- 9 agents, 18 files
- Add file_type field to frontmatter
- Resolves ~200+ validation errors

Priority 2: Medium Effort 🟡

fix: decisions-framework - Resolve Markdown linting errors #1511 — docs: fix markdown linting errors in DECISIONS_FRAMEWORK document
- 309 linting issues
- Fix link fragments, list numbering, whitespace
- Improves CI/CD validation pipeline

Priority 3: Low Priority 🔵

chore: fix unused error variable warnings (underscore prefix convention) #1512 — chore: fix unused error variable warnings (underscore prefix convention)
- 68 ESLint warnings
- Rename catch variables to follow _variable pattern
- Code quality improvement

Summary

Scope: Pre-existing technical debt (confirmed not introduced by Repository Infrastructure Cleanup: ESLint & Footer Validation (Housekeeping Epic) #1486)
Blockers: None — main infrastructure cleanup (Repository Infrastructure Cleanup: ESLint & Footer Validation (Housekeeping Epic) #1486) is complete ✅
Effort: ~2-4 hours total across all three issues
Timeline: Flexible — schedule based on sprint priorities

Restructured 2026-08-04 by Claude Code

refactor: delete .github/agents folder per Phase 1 restructuring (#1510)

refactor: delete .github/agents per Phase 1 restructuring (#1510) (#1537

fix: add file_type frontmatter to root agent files (#1510)

Navigation Menu

Repository navigation

epic: pre-existing validation errors cleanup (3 child issues) #1507

Overview

Pre-Existing Issues Found

1. Frontmatter Validation Errors (542+ errors)

2. Markdown Linting Errors (309 issues)

3. ESLint Warnings (68 warnings)

Context

Recommendations

Priority 1: Frontmatter Fixes (Quick Win)

Priority 2: Markdown Linting (Medium Effort)

Priority 3: ESLint Warnings (Low Priority)

Related

Definition of Ready (DoR)

Definition of Done (DoD)

⏱️ Aging and SLA annotation

Clarification

Should This Issue Exist?

Epic Restructure ✅

Child Issues (Linked Work Items)

Priority 1: Quick Win 🟢

Priority 2: Medium Effort 🟡

Priority 3: Low Priority 🔵

Summary

3 remaining items

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

epic: pre-existing validation errors cleanup (3 child issues) #1507

Description

Overview

Pre-Existing Issues Found

1. Frontmatter Validation Errors (542+ errors)

2. Markdown Linting Errors (309 issues)

3. ESLint Warnings (68 warnings)

Context

Recommendations

Priority 1: Frontmatter Fixes (Quick Win)

Priority 2: Markdown Linting (Medium Effort)

Priority 3: ESLint Warnings (Low Priority)

Related

Definition of Ready (DoR)

Definition of Done (DoD)

Activity

linear-code commented on Aug 4, 2026

github-actions commented on Aug 4, 2026

github-actions commented on Aug 4, 2026

⏱️ Aging and SLA annotation

ashleyshaw commented on Aug 4, 2026

Clarification

Should This Issue Exist?

ashleyshaw commented on Aug 4, 2026

Epic Restructure ✅

Child Issues (Linked Work Items)

Priority 1: Quick Win 🟢

Priority 2: Medium Effort 🟡

Priority 3: Low Priority 🔵

Summary

3 remaining items

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions