brief-gate

name

brief-gate

description

Run a structured pre-task alignment interview for complex or ambiguous work. Use when the user asks to be grilled, wants questions before execution, requests requirements discovery or scope alignment, or when unresolved goals, constraints, tradeoffs, risks, or acceptance criteria could materially change a complex task. Present independent decisions together in a visual questionnaire, adapt later rounds to prior answers, and require explicit approval before implementation or return the approved brief to a calling controller skill.

BriefGate

Turn vague or decision-heavy work into an approved execution contract. Preserve the rigor of a one-question-at-a-time interview while batching only decisions that can be answered independently at the same point in the decision graph.

Use the bundled questionnaire generator to create Codex-compatible inline visuals. BriefGate has no runtime dependency on another skill.

Non-Negotiable Rules

• Do not implement, modify live state, publish, restart, delete, or otherwise execute the target task until the user approves the final alignment brief.
• Inspect the available environment first. Resolve discoverable facts from files, code, tools, documentation, or current system state instead of asking the user.
• Ask the user for decisions, preferences, authority boundaries, and unavailable business context. Never ask them to supply facts that can be verified locally.
• Never request passwords, access tokens, cookies, private keys, patient identifiers, or other secrets. Ask whether required access exists, not for the credential value.
• Preserve every confirmed answer. Do not ask it again unless new evidence creates a specific conflict.
• State a recommended answer for each decision and expose the material tradeoff. Recommendations remain proposals until selected.
• Keep dependent decisions in later rounds. Batch only questions whose prerequisites are already resolved.
• Stop interviewing as soon as the remaining ambiguity cannot materially change scope, architecture, risk, cost, or acceptance.
• Treat silence or an omitted optional answer as unresolved, not consent.
• When aligning a child milestone under a broader product or project contract, preserve the parent outcome and explicitly distinguish milestone acceptance from parent-goal completion.
• When a controller skill sets returnTo, return the approved brief to that caller instead of implementing, decomposing, or launching execution.

Workflow

1. Frame the Target

Restate the candidate task internally as:

• desired outcome;
• known deliverables;
• affected users or systems;
• irreversible or high-cost actions;
• current evidence;
• unresolved decisions.

For high-stakes or externally changing facts, refresh the current state before drafting questions.

2. Build a Decision Graph

Separate findings into a compact alignment ledger:

State	Meaning
Confirmed	Explicitly stated by the user or verified from evidence
Proposed	Codex recommendation awaiting a decision
Open	Decision that can be asked now
Blocked	Decision waiting on another answer or investigation
Deferred	Explicitly outside this task
Conflict	Two requirements or pieces of evidence cannot both hold

Keep the ledger in conversation context. Do not create a persistent state file unless the user requests one.

Select the current decision frontier: unresolved decisions whose prerequisites are all confirmed. Questions on the same frontier may appear together; blocked questions may not.

3. Design One Round

Use 4-8 questions for a normal discovery round. Use fewer only when fewer material decisions remain or when presenting the final approval gate.

Prefer, in order:

1. radio choices for one decision;
2. checkboxes for an intentional combination;
3. select controls for longer option sets;
4. short text for a value that cannot be enumerated;
5. textarea only for context that genuinely needs explanation.

Limit a normal round to at most two free-text controls. Include a safe escape such as "Use Codex recommendation", "Not sure", or "Defer" when appropriate. Do not use an "Other" option unless custom input is actually supported.

Group questions into 2-4 concise sections. For every choice question:

• mark one recommendation when Codex has enough evidence;
• explain each material option in one sentence;
• phrase choices as decisions, not vague sentiment;
• avoid presenting implementation details the user cannot reasonably evaluate.

Normal discovery should converge in 1-3 rounds. Exceed three only when the task is high-risk and the user agrees to continue.

4. Generate the Visual Questionnaire

Read references/questionnaire-schema.md when constructing or changing a questionnaire spec.

1. Write a temporary JSON spec containing questions only. Do not place user answers or secrets in the file.
2. Choose a new lowercase hyphenated HTML filename in the current thread-scoped visualization directory.
3. Run node scripts/build-questionnaire.mjs --input <spec.json> --output <visualization.html>, resolving both paths from this skill's directory and the current thread context.
4. Read the generated fragment back. Verify that it contains no document wrapper, escaped literal markup, external calls, or undefined element references.
5. Present one short sentence above the exact ::codex-inline-vis{file="<filename>.html"} directive. Do not duplicate all questions in prose.

When another controller skill invokes the interview, set returnTo to its skill reference, such as $project-controller, in every round including the approval gate. Preserve the same caller across rounds.

Localize all visible labels and validation messages to the user's language. Keep the follow-up prompt's skill name as $brief-gate so the next round reliably resumes this workflow.

If the inline visual surface is unavailable, ask the same independent questions as one concise numbered batch in chat and request answers keyed by number. Do not fall back to one-message-per-question unless dependencies require it.

5. Process a Submitted Round

The questionnaire sends a structured follow-up containing the round, stage, and answers.

1. Parse the submitted answer payload.
2. Merge it into the alignment ledger.
3. Detect omissions, contradictions, newly blocked branches, and facts that now need investigation.
4. Investigate discoverable facts before asking again.
5. Generate only the next decision frontier, or stop if alignment is sufficient.

Do not repeat a full history in each round. Carry forward only the compact confirmed decisions needed to interpret the next questions.

6. Present the Approval Gate Or Return To Caller

When no material ambiguity remains, show an alignment brief in prose with exactly these headings:

• Goal
• In Scope
• Out of Scope
• Constraints
• Acceptance Checks
• Risks and Assumptions
• Decisions Delegated to Codex
• First Execution Step

Clearly label any remaining inference. Then choose the completion route:

• Direct mode: generate a final visual gate with Approve and start, Revise specific decisions, and Ask another focused round.
• Controller-return mode: generate a final visual gate with Approve and return to <caller>, Revise specific decisions, and Ask another focused round.

In controller-return mode, approval must invoke the named caller with the approved alignment brief. Do not set the project goal, decompose work, choose execution mode, invoke another execution skill, or implement the target inside this skill. The caller owns those actions. Set First Execution Step to returning the brief to the named caller for goal setting and decomposition, not to a target implementation action.

When the brief covers a child milestone, include parent-contract traceability in the existing headings: state what the milestone advances, what remains unproven at the parent level, and who owns the parent-level closure check.

Recommend approval only when the brief is internally consistent and testable. In direct mode, start execution only after explicit approval. In controller-return mode, return control only after explicit approval.

Quality Check

Before showing each round, verify:

• every question could materially change the work;
• no answer is already available from the environment;
• questions in this round do not depend on each other;
• option labels are mutually exclusive where required;
• recommendations have a defensible reason;
• required fields are genuinely required;
• no sensitive value is requested;
• the visual remains usable at 320px width;
• the completion route is either direct execution or one explicit caller, not both;
• child-milestone acceptance cannot be misread as parent-goal completion;
• the next action after submission is unambiguous.