[meta-feedback] domain-discovery (mixed)

[KyleAMathews]

Meta-Skill Feedback: domain-discovery

Library: typography.js
Agent: claude-code
Artifact quality: mixed
Rating: mixed
Interview quality: bad

What Worked

The concept inventory approach is sound — listing library name, repo, docs, scope, and concepts per domain produces a useful map. The domain_map.yaml + skill_spec.md artifacts are a clean separation of concerns.

What Failed

"Target audience" is a meaningless input for Intent skills — skills are consumed by AI coding agents, not end users. The scaffold prompt dumps all three phases at once, causing the AI to skip the maintainer interview and autonomously generate everything. No instruction to load the actual domain-discovery SKILL.md before starting — the scaffold gives a summary but the full spec has critical format details. No success criteria step before writing skills. No guidance on identifying cross-cutting concerns that should become cross-references across skills (skills should form a semi-lattice, not isolated trees).

Suggestions

Present phases sequentially — only reveal Phase 2 after Phase 1 artifacts are confirmed. Replace "target audience" with "top use cases the AI should handle well". Add explicit instruction: "Load node_modules/@tanstack/intent/meta/domain-discovery/SKILL.md before starting." Add a guardrail: "STOP after generating artifacts. Present to maintainer for review. Do NOT proceed until they confirm." Add a step to identify cross-cutting concerns that will need cross-references across all skills. Add success criteria step: define what good looks like before writing skills. Teach maintainers to start with one basic skill, try tasks against it, iterate — not generate everything in one pass. The scaffold says to produce Markdown feedback but the CLI expects JSON — these are misaligned.

[KyleAMathews]

Additional feedback on the feedback submission process itself

The npx @tanstack/intent feedback --meta --submit command has several issues:

1. Scaffold says Markdown, CLI expects JSON. The scaffold prompt says "produce a single Markdown feedback doc" but the CLI parses the file as JSON. These are misaligned.

2. JSON feedback format produces ugly GitHub issues. The JSON → Markdown conversion loses structure. It would be better to have maintainers write a Markdown file per meta skill and submit directly via gh issue create. The current JSON intermediary adds friction without adding value.

3. Label creation fails silently. The CLI tries to add feedback:domain-discovery labels that don't exist on the TanStack/intent repo, causing the gh issue create call to fail. It then falls through to stdout with no error message explaining what went wrong — just prints the markdown.

4. Silent fallthrough to stdout. When the gh submission fails, the CLI prints the markdown to stdout without any indication that the submission failed. Should at minimum say "GitHub submission failed, printing markdown instead."

Suggested fix: The feedback skill should direct the agent to write a Markdown file per meta skill, then post it directly with gh issue create --repo TanStack/intent --title "[meta-feedback] <skill-name>" --body "$(cat feedback.md)". Skip the JSON intermediary entirely. Simpler, better formatting, fewer failure modes.

[KyleAMathews]

Follow-up: label creation should be part of setup

The feedback:domain-discovery, feedback:tree-generator, etc. labels need to exist on the repo before the feedback CLI can use them. Currently this fails silently at submission time — the worst possible moment to discover a setup issue.

Fix: npx @tanstack/intent setup (or a new npx @tanstack/intent setup --labels command) should create these labels on the target repo during initial setup. The labels are predictable from the meta skill names, so this can be fully automated. Fail loudly during setup, not silently during feedback submission.