Claude-skill-registry idea-normalizer

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/idea-normalizer" ~/.claude/skills/majiayu000-claude-skill-registry-idea-normalizer && rm -rf "$T"

manifest: skills/data/idea-normalizer/SKILL.md

Idea Normalizer â€” Agent Instructions

Invocation

Run this command with an idea folder id:

```
/idea-normalizer <IDEA_ID>
```

Where:

```
IDEA_REF = $ARGUMENTS
```
(must be a single token; no spaces)

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

docs/forge/ideas/<IDEA_ID>/inputs/normalizer_config.md

(optional)

docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.md

(optional; created in interactive mode)

Outputs:

Run folder:

docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/

Latest folder:
```
docs/forge/ideas/<IDEA_ID>/latest/
```

Per-idea logs:

```
docs/forge/ideas/<IDEA_ID>/run_log.md
```
(append-only)
```
docs/forge/ideas/<IDEA_ID>/manifest.md
```
(rolling status)

Directory handling

Ensure these directories exist (create them if missing):

```
docs/forge/ideas/<IDEA_ID>/inputs/
```
```
docs/forge/ideas/<IDEA_ID>/latest/
```
```
docs/forge/ideas/<IDEA_ID>/runs/
```

docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/

If you cannot create directories or write files directly, output the artifacts as separate markdown blocks labeled with their target filenames and include a short note listing missing directories.

Inputs

Required

idea.md

docs/forge/ideas/<IDEA_ID>/inputs/idea.md

Optional

normalizer_config.md

docs/forge/ideas/<IDEA_ID>/inputs/normalizer_config.md

normalizer_answers.md

docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.md

(if it exists)

idea.md

is missing, STOP and report the expected path.

Context (include file contents)

Use file references to pull content into context:

Raw idea: @docs/forge/ideas/<IDEA_ID>/inputs/idea.md
Optional config (only if it exists): @docs/forge/ideas/<IDEA_ID>/inputs/normalizer_config.md
Optional prior answers (only if it exists): @docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.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)

Always write a draft first

Write a draft to the run folder:

docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_normalized_draft.md

Write the Open Questions list for the run:

docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/open_questions.md

Final outputs (only after questions are resolved OR if no questions exist)

Write final
```
idea_normalized.md
```
to:

docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_normalized.md

Then also update:

docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md

(overwrite allowed)

Append an entry to:

```
docs/forge/ideas/<IDEA_ID>/run_log.md
```

Update (or create) the per-idea manifest at:

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

Interactive Open Questions Resolution (IMPORTANT)

Goal: avoid leaving key decisions as â€œOpen Questionsâ€ when the user can answer them now.

Default behavior

If Open Questions exist, you MUST ask the user those questions and capture their answers.
Exception: if
```
normalizer_config.md
```
explicitly sets
```
interactive: false
```
, then proceed without asking and keep Open Questions as-is.

Phase 1 â€” Draft + ask

After producing

idea_normalized_draft.md

and

open_questions.md

Present the questions to the user as a numbered list.
Ask the user to answer in the same numbered format.
STOP and wait for the userâ€™s reply.

Also append a run_log entry with:

Status:
```
NEEDS_USER_INPUT
```
Run-ID:
```
<RUN_ID>
```
Output draft paths

Phase 2 â€” Capture answers + finalize

When the user replies:

Save the userâ€™s answers to:

docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.md

Append a new section with header:

### <ISO-8601> â€” Answers for <RUN_ID>

Produce final
```
idea_normalized.md
```
:

Move answered items into the correct sections (Constraints, Preferences, Outputs, etc.)
Remove or reword answered questions from â€œOpen Questionsâ€
Keep any truly unresolved items in â€œOpen Questionsâ€

Write final outputs to

runs/<RUN_ID>/idea_normalized.md

and

latest/idea_normalized.md

Append a new run_log entry with:

Status:
```
SUCCESS
```
(or
```
SUCCESS_WITH_WARNINGS
```
if some questions remain unanswered)
Notes: include a bullet like
```
Resolved N open questions; remaining M
```

Definition: Normalization

Normalization means:

Preserve meaning and scope of the source idea
Re-express in consistent sections/terminology
Make implicit structure explicit (inputs, workflow, outputs, constraints, exclusions)
Record uncertainties instead of guessing

Normalization does NOT mean:

Adding new requirements
Choosing tech stacks not stated in the source
Writing implementation plans, epics, features, or tasks

Scope & Rules

You MUST

Preserve original intent and scope from
```
idea.md
```
Use the required section template below
Convert free-form text into concise bullets where appropriate
Mark assumptions explicitly as assumptions
Capture constraints and exclusions explicitly
Include â€œOpen Questionsâ€ for missing decisions (only those that remain after interactive resolution)

You MUST NOT

Introduce new scope or features not present in
```
idea.md
```
Redesign the system
Produce backlog items
Remove meaningful nuance; if unsure, keep detail and place it in the correct section

How to Normalize (Method)

Read entire
```
idea.md
```
once
Extract key statements into scratch (do not output scratch)
Map statements into the standard sections
Rewrite in consistent modality:
- Must / Should / May
Handle contradictions conservatively (record in Open Questions)
Keep it brief but complete (prefer bullets)

Output Format:

idea_normalized.md

(Markdown + YAML header)

Write

idea_normalized.md

with a YAML header followed by required sections.

YAML header (example)

---
doc_type: idea_normalized
idea_id: "<IDEA_ID>"
run_id: "<RUN_ID>"
generated_by: "Idea Normalizer"
generated_at: "<ISO-8601>"
source_inputs:
  - "docs/forge/ideas/<IDEA_ID>/inputs/idea.md"
configs:
  - "docs/forge/ideas/<IDEA_ID>/inputs/normalizer_config.md (if used)"
  - "docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.md (if used)"
status: "Draft"
---

Required sections

Idea (Normalized)

Summary

(1 short paragraph)

Goals

Target Users

Primary Use Cases

Inputs

Outputs

Conceptual Workflow

Core Capabilities

The system can ...

Constraints

Preferences

Out-of-Scope / Exclusions

Terminology

Term: meaning

Open Questions / Ambiguities

Logging Requirements:

run_log.md

(append-only)

Append an entry with this shape:

### <ISO-8601 timestamp> â€” Idea Normalizer

- Idea-ID: <IDEA_ID>
- Run-ID: <RUN_ID>
- Inputs:
  - docs/forge/ideas/<IDEA_ID>/inputs/idea.md
  - docs/forge/ideas/<IDEA_ID>/inputs/normalizer_config.md (if present)
  - docs/forge/ideas/<IDEA_ID>/inputs/normalizer_answers.md (if present)
- Outputs:
  - runs/<RUN_ID>/idea_normalized_draft.md
  - runs/<RUN_ID>/open_questions.md
  - runs/<RUN_ID>/idea_normalized.md (final, if produced)
  - latest/idea_normalized.md (final, if produced)
- Notes:
  - <1â€“5 bullets on key clarifications or ambiguities>
- Status: NEEDS_USER_INPUT | SUCCESS | SUCCESS_WITH_WARNINGS | FAILED

Manifest updates:

manifest.md

(per-idea)

manifest.md

does not exist, create it using the template below. If it exists, update ONLY the keys under the

Idea

section.

Manifest template (if creating new)

# Manifest â€” <IDEA_ID>

## Idea

- idea_normalized_status: Draft
- last_updated: <YYYY-MM-DD>
- last_run_id: <RUN_ID>
- latest_outputs:
  - latest/idea_normalized.md
- notes:
  - <optional bullets>

Do not add epics/features/tasks here.

Failure handling

idea.md

is extremely short/vague:

Produce the normalized template anyway
Put missing items into Open Questions
Do not invent details