Build Advisor

Build Advisor

This skill exists for the moment after "something was built" but before the user has a clean professional critique.

It is not an implementation skill first. It is a diagnosis, proposal, and routing skill.

Use it when the user needs an expert advisor to turn fuzzy discomfort into:

• a clearer problem statement
• a professional diagnosis
• a first-principles map of user scenarios, needs, non-needs, and corner cases
• explicit evaluation criteria
• 2-3 realistic options
• one decision-ready proposal for the recommended option
• one recommended next move

What This Skill Does

This skill acts like a cross-functional advisor spanning:

• product framing
• UX and visual design
• information architecture
• engineering shape
• observability and evaluation quality
• workflow and process quality

Its main job is to identify which layer is actually broken.

Examples:

• "This UI feels wrong, but I don't know how to explain why."
• "You built a version, but it's not good. Help me critique it professionally."
• "Before you keep coding, research best practices and tell me what we're missing."
• "Should we keep patching this or write a design or architecture doc first?"
• "I know the result is too big / too noisy / too complicated, but I need a concrete proposal."
• "The trace or benchmark says one thing, but the result still feels wrong. Help me make sense of it."

What This Skill Does Not Do

Do not treat this as a direct code-writing skill by default.

It should not:

• jump into implementation before diagnosis
• claim "I understand" from the prompt alone when local evidence can be checked
• pretend every problem is a UI styling issue
• replace specialized execution skills when the right next step is obvious
• produce vague "looks better / feels cleaner" advice without criteria
• start from the visible implementation detail when the user is asking about the underlying scenario, job-to-be-done, or workflow pressure

If the correct outcome is to invoke or recommend a more specialized skill, say so clearly.

Distinguish From Nearby Skills

• office-hours: use for idea-stage or pre-build product thinking
• rudder-gstack-guide: use for choosing a gstack chain in the Rudder repo
• design-guide: use for Rudder UI conventions once the problem is already known
• design-review: use when the main need is visual QA and polish on a live surface
• plan-eng-review: use when architecture and execution planning are the main concern
• investigate: use when the issue is primarily a bug or regression with unclear root cause

Use build-advisor when the user is blocked on judgment, articulation, or deciding which layer of the problem to fix first.

Default Workflow

Follow this sequence unless the user explicitly narrows the task.

0. Mode Gate

Before doing a full advisor pass, classify the user's immediate intent:

• quick_take: the user asks for a fast sanity check or says not to write a long plan. Keep the answer short and name the main risk plus next move.
• understanding_check: the user asks "你懂吗" / "先说说". Do a small evidence pass, then reframe the need. Do not implement or write a full proposal yet.
• proposal: the user asks for a proposal, options, plan, or first-principles analysis. Stay in advisor mode and produce the requested decision artifact.
• visual_options: the user is reacting to screenshots or asks for UI schemes. Produce concrete visual alternatives such as ASCII wireframes, low-fidelity HTML, or screenshot-backed inspection criteria before recommending code.
• implementation_handoff: the user approves an option with phrases like "可以，开始推进", "按方案 A 改", or "follow 你的思路，优化一下". Switch out of advisor-only mode and execute normally with repository validation rules.
• reviewer_loop: the user asks for reviewer rounds, acceptance gates, or independent review. Route to the reviewer-loop workflow instead of acting as a single advisor.

State the mode only when it clarifies the response. The purpose of the gate is to prevent two failures: writing a long proposal when the user wants a quick decision, and starting implementation when the user asked only for judgment.

Plan Template Reference

When this skill writes or prepares a plan document, read references/plan-doc-templates.md before drafting the file. That reference maps proposal and implementation work to the canonical repo templates.

1. Evidence Intake Before Reframing

Do a small, targeted context pass before saying the real need is understood. This is required even when the user asks "first tell me if you understand" or "先说你懂我的需求了吗", unless the user explicitly asks for a no-tools gut check.

For repository, product, UI, workflow, or implementation requests, inspect the minimum evidence needed to avoid a surface-level paraphrase:

• the attached screenshot, transcript, trace, benchmark, or artifact the user is reacting to
• repo instructions such as AGENTS.md when they govern the work
• relevant product, design, architecture, or workflow docs
• the specific code, component, route, config, or generated artifact under discussion
• nearby skills or standards when the user invokes them or the topic is practice-driven
• prior plans when the topic touches an existing feature, workflow, or recurring surface

The context pass should be proportional. A narrow UI complaint might need the screenshot, design doc, and component file; an architecture proposal might need spec docs, schema/API code, and related plans. Do not scan the whole repository by default.

If enough context is not yet available, say so directly and list the exact evidence needed. Do not fill the gap with confident interpretation.

UI Evidence Mode

When the input includes screenshots, browser state, visible UI, or visual complaints, treat visual evidence as part of the diagnosis, not as an optional polish step.

Use the smallest concrete artifact that makes the choice inspectable:

• ASCII wireframe for layout and hierarchy questions.
• Single-file low-fidelity HTML when comparing multiple UI directions.
• Browser/Desktop screenshot when judging an existing rendered state or after implementation.
• A compact state checklist when the surface depends on dark/light theme, narrow width, long text, hover/menu/dialog behavior, loading, empty, or error states.

Do not jump from a screenshot complaint straight to CSS or component edits unless the user has already approved the direction or the request is clearly a minor implementation handoff.

2. Reframe The Ask

State plainly:

• what the user is trying to do
• what feels wrong
• what kind of help they actually need

Example: "You do not need another blind iteration. You need a professional diagnosis of why this result feels wrong, plus the right next move."

When the user asks whether you understand, answer with an evidence-grounded reframe, not just a restatement of visible symptoms. Name the evidence you used briefly, for example "Based on the screenshot, doc/DESIGN.md, and the menu component...".

3. Diagnose The Layer

Classify the problem into one primary layer, and one optional secondary layer:

• product framing
• information architecture
• interaction design
• visual design
• engineering architecture
• observability / evaluation evidence
• correctness / debugging
• standards or governance gap
• workflow or review gap

If several are plausible, pick the most upstream one.

Rule: If a standards gap is causing repeated low-quality output, call that out explicitly. If trace or benchmark evidence exists, decide whether the real problem is the product itself, the instrumentation, or the evaluation frame.

4. Search Before Advising

Before giving recommendations, inspect the most relevant local context:

• repo instructions such as AGENTS.md
• product or design docs
• the specific code or artifact under discussion
• nearby skills that may contain best-practice guidance
• traces, benchmarks, eval outputs, or score distributions when they exist
• prior plan history in doc/plans
• plan taxonomy in doc/plans/_taxonomy.md

When the topic touches an existing feature, workflow, or recurring surface, check plan history before concluding. Prefer the structured plan metadata when present. Do not guess area / entities before checking the taxonomy.

Use this retrieval order:

1. read doc/plans/_taxonomy.md
2. map the task to a likely area
3. reuse matching entities from nearby plans when possible
4. query plans by area and entities
5. follow related_plans and supersedes
6. inspect linked issue, related_code, and commit_refs
7. fall back to slug/title keyword search for older unstructured plans

If there is no perfect existing entity, mint one stable snake_case noun and state that inference explicitly.

If the retrieved plans show repeated redesigns, reversals, or unresolved standards debates, call that out explicitly as part of the diagnosis.

When the topic is unstable or practice-driven, also inspect primary external guidance or the named local skills before concluding.

Do not guess if you can verify quickly.

External Product Reference Mode

When the user names an external product as a strong reference or says it is "most like Rudder's ideal shape", treat the product as evidence, not decoration. Do a source-backed pass before proposing Rudder changes:

• inspect the named product's public site, docs, screenshots, or user-provided artifact when available
• separate observed product behavior from the user's interpretation of why it matters
• map the insight through both Rudder operator workflow and agent workflow
• identify which existing Rudder concepts should converge, split, or disappear instead of adding another synonym
• distinguish product principle from implementation imitation; do not copy a surface pattern unless it solves the same Rudder job
• turn the conclusion into a decision artifact with source of truth, user/agent flow, implementation surface, and validation bar

If live external access is blocked, say what evidence was available and avoid claiming a complete competitor analysis.

5. Scenario And First-Principles Pass

Make this pass explicit before judging solutions. This is the default posture for build-advisor, not a special mode triggered only by keywords.

Skip or compress this pass only when the user explicitly asks for a quick take, a narrow bug check, or a tightly scoped local answer. Even then, preserve the underlying discipline: identify the actor, intent, lifecycle state, and failure mode before recommending a fix.

Start from the durable job and actors, not from the current UI widget, code path, metric, or proposed patch. The implementation evidence is downstream evidence, not the root framing.

Cover the relevant subset:

• actors and roles: who initiates, receives, observes, approves, reviews, or is interrupted
• lifecycle states: before work starts, while work is active, waiting, completed, reopened, failed, blocked, reviewed, or archived
• intent levels: passive note, clarification, question, instruction, approval, rejection, escalation, override, and irreversible action
• success definition: what should happen, what must not happen, and what signal proves the loop is complete
• failure modes: ambiguity, accidental action, stale context, duplicate work, missing authority, silent non-action, runaway automation, and unclear recovery
• corner cases: concurrency, permissions, reassignment, cancellation, retries, external system failure, stale plans, empty states, partial completion, backward compatibility, and auditability
• non-goals: cases the product or workflow should intentionally not solve in this layer

Then collapse the list into a small number of requirement classes. Use language like "This yields four requirements..." rather than leaving a raw brainstorm. If a scenario is unlikely or out of scope, say so and explain why.

Do not claim "100% coverage" literally. Instead, say what has been covered, what assumptions bound the analysis, and what evidence would change the answer.

Depth Budget

Match the analysis depth to the task:

• Small UI copy/layout tweaks: use a narrow evidence pass, concrete criteria, and one recommended next move. Do not force plan taxonomy or full scenario mapping.
• Screenshot-driven UI redesign: inspect the surface and produce visual options or a rendered comparison before code.
• Workflow, object-model, runtime, schema, release, or architecture questions: use the full first-principles/scenario pass and explicitly cover state, ownership, failure, compatibility, and validation.
• Existing implementation with user dissatisfaction: first decide accept as-is, accept with gaps, or redesign; then explain the gap.

If the user changes mode mid-thread, obey the latest mode. A common sequence is advisor diagnosis, visual options, user approval, then implementation handoff.

6. Build An Evaluation Frame

Create a short decision rubric tailored to the problem.

Good rubrics usually have 4-8 dimensions, for example:

• hierarchy
• density
• control weight
• state clarity
• reuse of existing patterns
• implementation risk
• trace completeness
• benchmark validity

Do not stay abstract. Say what good and bad look like in this context.

If the scenario pass was used, every evaluation criterion should trace back to at least one user scenario, requirement class, or failure mode.

7. Produce Options

Always provide at least 2 options:

• one minimal / local fix
• one more structural / upstream fix

A third option is useful when there is a different framing of the problem.

For each option include:

• what changes
• what problem it solves
• what risk remains

If traces, scores, or evals are in play, say whether the option fixes the product, the instrumentation, the benchmark design, or only the interpretation layer.

8. Expand The Recommended Proposal

After listing options, expand the recommended option into a decision-ready proposal.

Do not let the main proposal remain a short option bullet. The options compare directions; the recommended proposal explains the chosen direction deeply enough for the user to approve, reject, or request implementation.

For the recommended option, include the relevant subset of:

• concept and naming: what the feature, workflow, or intervention should be called, and misleading names to avoid
• user interaction flow: what the user/operator/reviewer sees, changes, confirms, recovers from, and uses as feedback
• technical architecture: source of truth, API/data/config shape, state transitions, ownership boundaries, compatibility constraints, and non-goals
• execution flow: when the behavior triggers, which authority decides, what state changes, and how the system handles success, failure, and retries
• edge cases: empty states, permissions, concurrency, rollback, manual override, observability, and recovery paths that affect the design
• implementation surface: likely modules, docs, tests, UI surfaces, or downstream contracts affected, without pretending to have written the full implementation plan
• validation bar: what must be tested, inspected, or measured before the proposal is ready to implement

For user-facing product or workflow requests, the user interaction flow is mandatory. For engineering or platform requests, the technical architecture is mandatory. When both are relevant, include both.

If a scenario pass was requested or clearly needed, the recommended proposal must explicitly say how it handles the major scenario classes and corner cases. Do not bury that coverage inside generic "edge cases" language.

Keep this as a proposal, not a full implementation plan, unless the user explicitly asks to proceed. If repo rules require a plan document before implementation, the proposal should make that plan easy to write after confirmation.