OpenSkillIndex← back to search
claude-code

Claude-skill-registry feature-validator

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/feature-validator" ~/.claude/skills/majiayu000-claude-skill-registry-feature-validator && rm -rf "$T"
manifest: skills/data/feature-validator/SKILL.md
source content

Feature Validator — Agent Instructions

Invocation

Run this command with an idea folder id:

  • /validate-features <IDEA_ID>

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/<IDEA_ID>/

Inputs:

  • docs/forge/ideas/<IDEA_ID>/inputs/idea.md
    (required baseline input)
  • docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md
    (optional)
  • docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md
    (optional)
  • Prior report (optional): 
    docs/forge/ideas/<IDEA_ID>/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/<IDEA_ID>/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/<IDEA_ID>/latest/concept_summary.md
    (required; anchor)
  • docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md
    (preferred; boundaries)
  • docs/forge/ideas/<IDEA_ID>/latest/epics.md
    (fallback only if epics_backlog is missing)
  • docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md
    (preferred; subject)
  • docs/forge/ideas/<IDEA_ID>/latest/features.md
    (fallback only if features_backlog is missing)
  • docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md
    (optional; preferred structured context)

Outputs:

  • Run folder: 
    docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/validators/
  • Run outputs folder: 
    docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/
  • Latest folder: 
    docs/forge/ideas/<IDEA_ID>/latest/validators/

Per-idea logs:

  • docs/forge/ideas/<IDEA_ID>/run_log.md
    (append-only)
  • docs/forge/ideas/<IDEA_ID>/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/<IDEA_ID>/inputs/
  • docs/forge/ideas/<IDEA_ID>/latest/validators/
  • docs/forge/ideas/<IDEA_ID>/runs/
  • docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/validators/
  • docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/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/<IDEA_ID>/latest/concept_summary.md
    (required; anchor)
  2. docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md
    (preferred; epic boundaries)
  3. docs/forge/ideas/<IDEA_ID>/latest/epics.md
    (fallback if epics_backlog is missing)
  4. docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md
    (preferred; subject)
  5. docs/forge/ideas/<IDEA_ID>/latest/features.md
    (fallback if features_backlog is missing)
  6. docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md
    (preferred if present)
  7. docs/forge/ideas/<IDEA_ID>/inputs/idea.md
    (required baseline context)

Optional:

  • docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md
  • docs/forge/ideas/<IDEA_ID>/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/<IDEA_ID>/latest/concept_summary.md

  • Epics (preferred; fallback to epics.md if backlog missing): @docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md @docs/forge/ideas/<IDEA_ID>/latest/epics.md

  • Features (preferred; fallback to features.md if backlog missing): @docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md @docs/forge/ideas/<IDEA_ID>/latest/features.md

  • Preferred normalized idea (only if it exists): @docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md

  • Baseline raw idea (always): @docs/forge/ideas/<IDEA_ID>/inputs/idea.md

  • Optional configs (only if they exist): @docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md @docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md

  • Prior report (only if it exists): @docs/forge/ideas/<IDEA_ID>/latest/validators/feature_validation_report.md

  • Optional codebase context (only if it exists): @docs/forge/ideas/<IDEA_ID>/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/<IDEA_ID>/runs/<RUN_ID>/validators/feature_validation_report.md
  • Also update: 
    docs/forge/ideas/<IDEA_ID>/latest/validators/feature_validation_report.md
    (overwrite allowed)
  1. Append a run entry to:
  • docs/forge/ideas/<IDEA_ID>/run_log.md
  1. Update 
    docs/forge/ideas/<IDEA_ID>/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)

  1. Patched features backlog:
  • Write to: 
    docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/features_backlog.md
  • Also update: 
    docs/forge/ideas/<IDEA_ID>/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.
  1. 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
    ).
  1. 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).
  1. Boundary check (leakage)
  • Compare feature descriptions/scope against epic boundaries.
  • If a feature touches another epic’s scope, propose moving or splitting.
  1. 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
  1. Invariant/exclusion check
  • Any contradiction → Critical.
  1. Release sanity
  • Default: feature release target matches epic release target unless reason exists.
  • MVP set forms usable slice.
  1. 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):

---
doc_type: feature_validation_report
idea_id: "<IDEA_ID>"
run_id: "<RUN_ID>"
generated_by: "Feature Validator"
generated_at: "<ISO-8601>"
source_inputs:
  - "docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback if backlog missing)"
  - "docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback if backlog missing)"
  - "docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (if present)"
  - "docs/forge/ideas/<IDEA_ID>/inputs/idea.md"
configs:
  - "docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md (if used)"
  - "docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md (if used)"
status: "Draft"
---

Required sections:

Feature Validation Report

Summary

  • Overall verdict: PASS | PASS_WITH_WARNINGS | FAIL
  • Critical issues: <count>
  • Warnings: <count>
  • 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: <bullets>
  • Notes: <bullets>

Boundary Issues (Cross-Epic Leakage)

For each issue:

  • Type: LEAKAGE | MIS-SCOPED
  • Feature: FEAT-...
  • Assigned epic: EPIC-...
  • Suspected correct epic: EPIC-...
  • Evidence: <short explanation>
  • Recommended fix: <explicit edit>

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: <list>
  • Required fixes: <bullets>

Invariant & Exclusion Violations (Critical)

For each violation:

  • Invariant/Exclusion: <text>
  • 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/<IDEA_ID>/run_log.md
:

### <ISO-8601 timestamp> — Feature Validator

- Idea-ID: <IDEA_ID>
- Run-ID: <RUN_ID>
- Inputs:
  - docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md
  - docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md (preferred)
  - docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback if backlog missing)
  - docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md (preferred)
  - docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback if backlog missing)
  - docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (if present)
  - docs/forge/ideas/<IDEA_ID>/inputs/idea.md
  - docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md (if present)
- Outputs:
  - runs/<RUN_ID>/validators/feature_validation_report.md
  - latest/validators/feature_validation_report.md
  - runs/<RUN_ID>/outputs/features_backlog.md (only if produced)
  - latest/features_backlog.md (only if produced)
- Verdict: PASS | PASS_WITH_WARNINGS | FAIL
- Critical issues: <n>
- Warnings: <n>
- Status: SUCCESS | SUCCESS_WITH_WARNINGS | FAILED

Manifest Updates (per-idea)

Update or create a 

Validation
section in:

  • docs/forge/ideas/<IDEA_ID>/manifest.md

Add an entry for this run:

  • validator: Feature Validator
  • run_id: <RUN_ID>
  • verdict: PASS|WARN|FAIL
  • report_file: latest/validators/feature_validation_report.md
  • patched_file: latest/features_backlog.md (if produced)
  • last_updated: <YYYY-MM-DD>

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.