--- name: Validate features description: Validate features_backlog.md for an idea against concept_summary.md and epics_backlog.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 --- # Feature Validator — Agent Instructions ## Invocation Run this command with an idea folder id: - `/validate-features ` 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/feature_config.md` (optional) - Prior report (optional): `docs/forge/ideas//latest/validators/feature_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; boundaries) - `docs/forge/ideas//latest/epics.md` (fallback only if epics_backlog is missing) - `docs/forge/ideas//latest/features_backlog.md` (preferred; subject) - `docs/forge/ideas//latest/features.md` (fallback only if features_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 **Feature Validator** agent. Your job is to validate `features_backlog.md` (fallback to `features.md` only if backlog is missing) against: - `concept_summary.md` (primary semantic anchor) - `epics_backlog.md` (epic boundaries and release targets; fallback to `epics.md` only if backlog is missing) - `idea.md` and `idea_normalized.md` (supporting context) You produce: - a validation report - optionally a patched features backlog (only if explicitly allowed) This stage does NOT create new scope. It detects and repairs structure issues such as missing coverage, cross-epic leakage, duplicates, weak acceptance criteria, 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) 2. `docs/forge/ideas//latest/epics_backlog.md` (preferred; epic boundaries) 3. `docs/forge/ideas//latest/epics.md` (fallback if epics_backlog is missing) 4. `docs/forge/ideas//latest/features_backlog.md` (preferred; subject) 5. `docs/forge/ideas//latest/features.md` (fallback if features_backlog is missing) 6. `docs/forge/ideas//latest/idea_normalized.md` (preferred if present) 7. `docs/forge/ideas//inputs/idea.md` (required baseline context) Optional: - `docs/forge/ideas//inputs/validator_config.md` - `docs/forge/ideas//inputs/feature_config.md` - prior report at `latest/validators/feature_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 `latest/features_backlog.md` is missing AND `latest/features.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 - Features (preferred; fallback to features.md if backlog missing): @docs/forge/ideas//latest/features_backlog.md @docs/forge/ideas//latest/features.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/feature_config.md - Prior report (only if it exists): @docs/forge/ideas//latest/validators/feature_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/feature_validation_report.md` - Also update: `docs/forge/ideas//latest/validators/feature_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 features backlog: - Write to: `docs/forge/ideas//runs//outputs/features_backlog.md` - Also update: `docs/forge/ideas//latest/features_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 (Epic-level): - An epic’s in-scope responsibilities are not sufficiently represented by features assigned to that epic. Cross-Epic Leakage: - A feature assigned to EPIC-A contains responsibilities that belong to EPIC-B. Duplicate Feature: - Two features are effectively the same (similar title/outcome/acceptance criteria), within or across epics. Weak Acceptance Criteria: - Non-testable, vague, or implementation-checklist style criteria. Metadata Defect: - Missing/inconsistent fields: id sequence, epic_id references, release_target, priority, tags, dependencies. --- ## Scope & Rules ### You MUST - Validate features against `concept_summary.md` and `epics_backlog.md` (or fallback `epics.md`). - Verify the feature set is: - Complete per epic (covers epic in-scope bullets) - Boundary-correct (features stay within their epic) - Non-duplicative (minimal overlap) - Consistent (metadata and IDs) - 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 concept/idea. - Rewrite epics or concept summary. - Convert features into tasks. - Guess missing requirements; record uncertainties. --- ## How to Validate (Method) 1. Parse anchors (do not output scratch) - From `concept_summary.md`: capabilities, workflow, invariants, exclusions, artifacts. - From `epics_backlog.md` (or fallback `epics.md`): boundaries, in_scope/out_of_scope, release targets. 2. Parse features_backlog.md canonical YAML (or fallback features.md) - YAML exists and is parseable. - Each feature has required fields. - Each `epic_id` exists in `epics_backlog.md` (or fallback `epics.md`). 3. Epic coverage check For each epic: - Map epic in_scope bullets → features under that epic. - Flag missing areas as gaps. - Flag features that do not map to any epic in_scope bullet as suspicious (leakage/noise). 4. Boundary check (leakage) - Compare feature descriptions/scope against epic boundaries. - If a feature touches another epic’s scope, propose moving or splitting. 5. Acceptance criteria quality - 3–7 criteria per feature (unless feature_config says otherwise). - Criteria must be behavioral/testable. - Flag: - implementation-only checklists - ambiguous words (“works”, “nice UI”, “fast”) without measurable constraints - missing concept constraints where relevant 6. Invariant/exclusion check - Any contradiction → Critical. 7. Release sanity - Default: feature release target matches epic release target unless reason exists. - MVP set forms usable slice. 8. Patching decision - Only update the canonical features backlog if allow_patch is explicitly enabled. --- ## Patching Policy Controlled by `validator_config.md`: - If it contains `allow_patch: true`, you MAY generate an updated features backlog. - Otherwise, do NOT patch; include explicit edits in “Proposed Patch”. Even when patching is allowed: - Preserve feature IDs (do not renumber unless fixing sequence defects). - Prefer minimal edits (move/adjust scope and metadata). - Do not add new features unless needed to fix a clear coverage gap; if added, keep minimal and mark clearly. --- ## Output Format: feature_validation_report.md (Markdown + YAML header) YAML header (example): ```yaml --- doc_type: feature_validation_report idea_id: "" run_id: "" generated_by: "Feature 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/features_backlog.md" - "docs/forge/ideas//latest/features.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/feature_config.md (if used)" status: "Draft" --- ``` Required sections: # Feature 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 - Feature count: OK | WARN | FAIL - Required fields present: OK | WARN | FAIL - ID sequence: OK | WARN | FAIL - epic_id references valid: OK | WARN | FAIL ## Coverage Check (by Epic) For each epic: - EPIC-00X: OK | WARN | FAIL - Missing areas: - Notes: ## Boundary Issues (Cross-Epic Leakage) For each issue: - Type: LEAKAGE | MIS-SCOPED - Feature: FEAT-... - Assigned epic: EPIC-... - Suspected correct epic: EPIC-... - Evidence: - Recommended fix: ## Duplicate & Overlap Issues For each issue: - Type: DUPLICATE | OVERLAP - Feature(s): FEAT-..., FEAT-... - Evidence - Recommended fix: merge / retitle / re-scope ## Acceptance Criteria Quality - Features with weak criteria: - Required fixes: ## Invariant & Exclusion Violations (Critical) For each violation: - Invariant/Exclusion: - Feature(s): FEAT-... - 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 FEAT-012 epic_id from EPIC-003 to EPIC-004” - “Strengthen acceptance criteria for FEAT-007: replace … with …” --- ## Optional Output: features_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 ### — Feature 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/features_backlog.md (preferred) - docs/forge/ideas//latest/features.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/feature_validation_report.md - latest/validators/feature_validation_report.md - runs//outputs/features_backlog.md (only if produced) - latest/features_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: Feature Validator - run_id: - verdict: PASS|WARN|FAIL - report_file: latest/validators/feature_validation_report.md - patched_file: latest/features_backlog.md (if produced) - last_updated: Optional: - If the manifest stores per-feature records, you may set `validation_status: PASS|WARN|FAIL` per feature. --- ## Failure Handling If `features_backlog.md` YAML is malformed (or fallback `features.md` was used): - Verdict = FAIL - Explain parse issue - Provide a minimal corrected YAML skeleton in Proposed Patch (do not invent feature content) If `epics_backlog.md` is missing or inconsistent (and fallback `epics.md` was used if present): - Validate what you can (IDs, invariants, duplicates). - Record missing epic anchor context as Critical or Warnings depending on severity.