Taste Encoding

Taste Encoding

Extracts a user's design taste through structured interviews and encodes it into skill artifacts — reference files, decision rules, conventions, comparison tables, and anti-patterns. Taste is the difference between a generic skill ("here are 5 database options") and an opinionated one ("use D1 for small projects, Neon when you need RLS or compliance — here's exactly why").

Decision tree

• What does the user want?
  • Encode taste into a new skill → the skill doesn't exist yet. Hand off to the authoring skill (authoring) to scaffold the skill first, then come back here for taste encoding.
  • Encode taste into an existing skill → what's the current state?
    • Skill has no taste yet (generic, presents options without opinions) → run the full process below
    • Skill has some taste but gaps remain → read the skill, identify which domains still lack opinions, run a focused interview on those gaps only
    • Skill taste is stale or wrong → read the skill, ask the user what changed, update the relevant reference files
  • Review how taste is encoded in a skill → read the skill's SKILL.md and reference files, assess against the patterns in references/encoding-patterns.md, report gaps
  • Interview without a specific skill target → run the interview, save findings to a structured document the user can apply later

Full process

1. Scope the domain

Read the target skill's SKILL.md and any existing reference files. Identify:

• What decisions does this skill guide? (e.g., data modeling → ID strategy, naming, tenancy, migrations)
• Which decisions are currently generic (presenting options without recommending one)?
• Which decisions are missing entirely?

List the taste gaps — these become the interview topics.

2. Interview

Use the host's structured question mechanism when one is available, such as AskUserQuestion, request_user_input, or an equivalent UI prompt. If no structured question tool is available, ask concise plain-text questions directly. In either mode, ask 1-3 related questions at a time and wait for answers before continuing.

Follow references/interview-guide.md for the full interview protocol. The essentials: open with known context, ask about decisions rather than abstract preferences, capture the "because" behind strong opinions, batch questions by theme, weigh trade-offs actively, and stop when the user has no strong opinion.

3. Organize findings

Group interview answers into categories:

4. Encode

Transform organized findings into skill artifacts using references/encoding-patterns.md. Prefer rationale-backed rules, comparison tables for context-dependent choices, anti-patterns with stories, and a philosophy or principles reference when three or more decisions share the same underlying principle.

For each artifact:

1. Write the reference file (or update existing ones)
2. Update SKILL.md to reference it — add to the key references table, link from relevant decision tree branches or workflow steps
3. Inline the most critical 1-2 sentence summary in SKILL.md itself so the agent gets the gist without reading the reference

Multi-skill encoding: When encoding taste across multiple skills at once, offer to fan out step 4 to parallel agents — one Encoder agent per target skill, each receiving only that skill's organized findings. This avoids serializing work on independent files. For a single skill, stay single-agent.

5. Validate

After encoding:

1. Read the updated SKILL.md end-to-end — does an agent following it produce opinionated output aligned with the user's taste?
2. Check that every encoded preference has a rationale (the "because")
3. Check that decision rules have clear conditions, not vague ones ("when it makes sense" → bad, "when you need RLS or multi-tenant isolation" → good)
4. Run the token-estimate tool from the authoring skill (../authoring/tools/token-estimate.ts) on the SKILL.md to verify it's still under 5000 tokens — taste encoding can bloat the main file if you inline too much
5. Confirm no reference file exceeds ~300 lines — split if needed

Present a summary to the user: what was encoded, where it lives, and any decisions that were left generic (with reasoning).

Focused interview (for filling gaps)

When a skill already has some taste but not enough:

1. Read all existing reference files and conventions
2. List what's already encoded vs what's generic
3. Interview only the gaps — skip topics where the skill is already opinionated
4. Encode findings into the existing structure (update files, don't create parallel ones)

Key references