--- name: Validate epics description: Validate epics_backlog.md for an idea against concept_summary.md (writes report to ideas//runs and updates ideas//latest; optional patch if allowed) argument-hint: " (example: IDEA-0003_my-idea)" disable-model-invocation: true --- # Epic Validator — Agent Instructions ## Invocation Run this command with an idea folder id: - `/validate-epics ` Where: - `IDEA_REF = $ARGUMENTS` (must be a single token; no spaces) If `IDEA_REF` is missing/empty, STOP and ask the user to rerun with an idea id. --- ## Resolve IDEA_ID (required) Before using any paths, resolve the idea folder: - Call `vf.resolve_idea_id` with `idea_ref = $ARGUMENTS` - Store the returned `idea_id` as `IDEA_ID` - Use `IDEA_ID` for all paths, YAML headers, and run log entries --- ## Canonical paths (repo-relative) Idea root: - `docs/forge/ideas//` Inputs: - `docs/forge/ideas//inputs/idea.md` (required baseline input) - `docs/forge/ideas//inputs/validator_config.md` (optional) - `docs/forge/ideas//inputs/epic_config.md` (optional) - Prior report (optional): `docs/forge/ideas//latest/validators/epic_validation_report.md` ### Optional codebase anchor (recommended) If it exists, use `codebase_context.md` to keep backlog items aligned with the current architecture and to avoid inventing parallel subsystems. - `docs/forge/ideas//latest/codebase_context.md` (optional) How to use it: - Prefer extending existing entrypoints/patterns mentioned in `codebase_context.md` - Avoid proposing new top-level modules if `codebase_context.md` indicates extension points - If `codebase_context.md` conflicts with the idea docs, record the conflict as an Open Question (do not guess) Upstream artifacts (required unless noted): - `docs/forge/ideas//latest/concept_summary.md` (required; anchor) - `docs/forge/ideas//latest/epics_backlog.md` (preferred; required if present) - `docs/forge/ideas//latest/epics.md` (fallback only if epics_backlog is missing) - `docs/forge/ideas//latest/idea_normalized.md` (optional; preferred structured context) Outputs: - Run folder: `docs/forge/ideas//runs//validators/` - Run outputs folder: `docs/forge/ideas//runs//outputs/` - Latest folder: `docs/forge/ideas//latest/validators/` Per-idea logs: - `docs/forge/ideas//run_log.md` (append-only) - `docs/forge/ideas//manifest.md` (rolling status/index) --- ## Reuse-first sanity check (repo-aware) If `codebase_context.md` exists: - Confirm the backlog does not propose a parallel subsystem where an extension point already exists. - If duplication risk is detected, flag it as a validation warning with suggested consolidation. If validating tasks and `existing_solution_map.md` exists: - Ensure tasks reference the touch list (files/modules) and contain reuse notes. - Warn if tasks are generic (“create new service”) without mapping to existing components. --- ## Directory handling Ensure these directories exist (create them if missing): - `docs/forge/ideas//inputs/` - `docs/forge/ideas//latest/validators/` - `docs/forge/ideas//runs/` - `docs/forge/ideas//runs//validators/` - `docs/forge/ideas//runs//outputs/` If you cannot create directories or write files directly, output artifacts as separate markdown blocks labeled with their target filenames and include a short note listing missing directories. --- ## Role You are the **Epic Validator** agent. Your job is to validate `epics_backlog.md` (fallback to `epics.md` only if backlog is missing) against the source intent and boundaries defined by: - `concept_summary.md` (primary anchor) - `idea.md` and `idea_normalized.md` (supporting context) You produce: - a validation report - optionally a patched epics backlog (only if explicitly allowed) This stage does NOT create new scope. It detects and repairs structure issues such as gaps, overlaps, duplicates, and inconsistent metadata. --- ## Inputs (how to choose sources) You MUST read inputs in this order: 1. `docs/forge/ideas//latest/concept_summary.md` (required; anchor truth) 2. `docs/forge/ideas//latest/epics_backlog.md` (preferred; subject) 3. `docs/forge/ideas//latest/epics.md` (fallback if epics_backlog is missing) 4. `docs/forge/ideas//latest/idea_normalized.md` (preferred if present) 5. `docs/forge/ideas//inputs/idea.md` (required baseline context) Optional: - `docs/forge/ideas//inputs/validator_config.md` - `docs/forge/ideas//inputs/epic_config.md` - prior report at `latest/validators/epic_validation_report.md` (if present) If `latest/concept_summary.md` is missing, STOP and report the expected path. If `latest/epics_backlog.md` is missing AND `latest/epics.md` is missing, STOP and report the expected path. If `inputs/idea.md` is missing, STOP and report the expected path. --- ## Context (include file contents) Include content via file references: - Concept summary (required): @docs/forge/ideas//latest/concept_summary.md - Epics (preferred; fallback to epics.md if backlog missing): @docs/forge/ideas//latest/epics_backlog.md @docs/forge/ideas//latest/epics.md - Preferred normalized idea (only if it exists): @docs/forge/ideas//latest/idea_normalized.md - Baseline raw idea (always): @docs/forge/ideas//inputs/idea.md - Optional configs (only if they exist): @docs/forge/ideas//inputs/validator_config.md @docs/forge/ideas//inputs/epic_config.md - Prior report (only if it exists): @docs/forge/ideas//latest/validators/epic_validation_report.md - Optional codebase context (only if it exists): @docs/forge/ideas//latest/codebase_context.md --- ## Run identity Generate: - `RUN_ID` as a filesystem-safe id (Windows-safe, no `:`), e.g.: - `2026-01-10T19-22-41Z_run-8f3c` Also capture: - `generated_at` as ISO-8601 time (may include timezone offset) --- ## Outputs ### Required outputs 1. Validation report: - Write to: `docs/forge/ideas//runs//validators/epic_validation_report.md` - Also update: `docs/forge/ideas//latest/validators/epic_validation_report.md` (overwrite allowed) 2. Append a run entry to: - `docs/forge/ideas//run_log.md` 3. Update `docs/forge/ideas//manifest.md` with validation metadata - Update only the exact subsection that matches your stage. Do not create unrelated headings. ### Optional output (only if patching is allowed) 4. Patched epics backlog: - Write to: `docs/forge/ideas//runs//outputs/epics_backlog.md` - Also update: `docs/forge/ideas//latest/epics_backlog.md` (overwrite allowed) If patching is not allowed, do NOT update the canonical backlog. Instead include a “Proposed Patch” section inside the report. --- ## Definitions Coverage Gap: - A core concept/capability/workflow step described in `concept_summary.md` has no corresponding epic. Overlap: - Two or more epics claim responsibility for the same work area/artifact/responsibility. Duplicate: - Two epics are effectively the same with no meaningful distinction. Mis-scoped Epic: - An epic includes responsibilities belonging elsewhere or violating exclusions/invariants. Metadata Defect: - Missing/inconsistent fields: id sequence, release_target, priority, tags, dependencies. --- ## Scope & Rules ### You MUST - Validate epics against `concept_summary.md` (anchor truth). - Verify the epic set is: - Complete (covers all major capabilities/workflow/artifacts) - Non-overlapping (clear ownership boundaries) - Consistent (IDs, metadata, release targets) - Aligned (does not violate invariants/exclusions) - Produce actionable findings with concrete recommended fixes. - Prefer minimal changes that preserve the author’s intent. ### You MUST NOT - Introduce new product scope beyond the concept/idea. - Rewrite the concept or redefine invariants. - Convert epics into features or tasks. - Guess; record uncertainties instead. --- ## How to Validate (Method) 1. Parse the Concept Summary (do not output scratch) - Extract: Core Capabilities, Workflow steps, Invariants, Constraints, In-Scope, Exclusions, Primary Artifacts, Entities. 2. Parse epics_backlog.md canonical YAML (or fallback epics.md if backlog missing) - YAML exists and is parseable - Epic count 6–12 unless epic_config says otherwise - Each epic has required fields: - id, title, outcome, description, in_scope, out_of_scope, release_target, priority, tags 3. Coverage mapping - Map each capability and workflow step to 1+ epics - Zero → GAP - Many → potential OVERLAP 4. Boundary analysis - Compare epics pairwise for overlap - Propose minimal boundary edits: - Move specific bullets - Add explicit out_of_scope bullets - Retitle when needed 5. Invariant/exclusion check - If any epic contradicts an invariant/exclusion → Critical issue 6. Release target sanity - MVP epics form coherent first deliverable - If MVP misses essential path → Critical gap - If MVP includes too much → retarget suggestions (V1/Full/Later) 7. Patching decision - Only update the canonical epics backlog if allow_patch is explicitly enabled. --- ## Patching Policy Patching is controlled by `validator_config.md`: - If it contains `allow_patch: true`, you MAY generate an updated epics backlog. - Otherwise, you MUST NOT patch; include “Proposed Patch” edits in the report. Even when patching is allowed: - Preserve epic IDs (do not renumber unless fixing sequence defects is required). - Prefer minimal edits; avoid rewriting descriptions unless necessary. --- ## Output Format: epic_validation_report.md (Markdown + YAML header) YAML header (example): ```yaml --- doc_type: epic_validation_report idea_id: "" run_id: "" generated_by: "Epic Validator" generated_at: "" source_inputs: - "docs/forge/ideas//latest/concept_summary.md" - "docs/forge/ideas//latest/epics_backlog.md" - "docs/forge/ideas//latest/epics.md (fallback if backlog missing)" - "docs/forge/ideas//latest/idea_normalized.md (if present)" - "docs/forge/ideas//inputs/idea.md" configs: - "docs/forge/ideas//inputs/validator_config.md (if used)" - "docs/forge/ideas//inputs/epic_config.md (if used)" status: "Draft" --- ``` Required sections: # Epic Validation Report ## Summary - Overall verdict: PASS | PASS_WITH_WARNINGS | FAIL - Critical issues: - Warnings: - Suggested patching: YES | NO (and why) ## Required-Field Checks - YAML parse: OK | FAIL - Epic count: OK | WARN | FAIL - Required fields present: OK | WARN | FAIL - ID sequence: OK | WARN | FAIL ## Coverage Check ### Coverage by Concept Capability - Capability: → EPIC-00X (or MISSING) ### Coverage by Workflow Step - Step: → EPIC-00X (or MISSING) ## Overlap & Boundary Issues For each issue: - Type: OVERLAP | DUPLICATE | MIS-SCOPED - Epic(s): EPIC-... - Evidence: - Recommended fix: ## Invariant & Exclusion Violations (Critical) For each violation: - Invariant/Exclusion: - Epic(s): EPIC-... - Why it violates - Minimal fix ## Release Target & Priority Sanity - MVP coherence: OK | WARN | FAIL - Notes on retargeting suggestions ## Metadata Defects - Missing tags, inconsistent tags, missing dependencies, etc. - Recommended fixes ## Proposed Patch (if patching not allowed) Provide explicit edits: - “Change EPIC-003 in_scope: add …; remove …” - “Set EPIC-005 release_target: V1” --- ## Optional Output: epics_backlog.md (only if allowed) If produced: - Preserve original format (YAML + Markdown rendering) - Apply only minimal changes identified in report --- ## Logging Requirements: run_log.md (append-only) Append an entry to `docs/forge/ideas//run_log.md`: ```md ### — Epic Validator - Idea-ID: - Run-ID: - Inputs: - docs/forge/ideas//latest/concept_summary.md - docs/forge/ideas//latest/epics_backlog.md (preferred) - docs/forge/ideas//latest/epics.md (fallback if backlog missing) - docs/forge/ideas//latest/idea_normalized.md (if present) - docs/forge/ideas//inputs/idea.md - docs/forge/ideas//inputs/validator_config.md (if present) - Outputs: - runs//validators/epic_validation_report.md - latest/validators/epic_validation_report.md - runs//outputs/epics_backlog.md (only if produced) - latest/epics_backlog.md (only if produced) - Verdict: PASS | PASS_WITH_WARNINGS | FAIL - Critical issues: - Warnings: - Status: SUCCESS | SUCCESS_WITH_WARNINGS | FAILED ``` --- ## Manifest Updates (per-idea) Update or create a `Validation` section in: - `docs/forge/ideas//manifest.md` Add an entry for this run: - validator: Epic Validator - run_id: - verdict: PASS|WARN|FAIL - report_file: latest/validators/epic_validation_report.md - patched_file: latest/epics_backlog.md (if produced) - last_updated: Optional: - If the manifest stores per-epic records, you may set `validation_status: PASS|WARN|FAIL` per epic. --- ## Failure Handling If `epics_backlog.md` YAML is malformed (or fallback `epics.md` was used): - Verdict = FAIL - Explain parse issue - Provide a minimal corrected YAML skeleton in “Proposed Patch” (do not invent epic content) If the concept summary is missing key sections: - Proceed best-effort - Record missing anchor info as warnings