Skip to content

workflows.md

Latest commit

 

History

History
155 lines (112 loc) · 5.75 KB

workflows.md

File metadata and controls

155 lines (112 loc) · 5.75 KB
Raw

Workflows

ExplainGate selects a mode from your request and current situation. You can name the mode explicitly, but plain language works too.

Documentation · Getting started · Visual artifacts · Gates and data · Troubleshooting

Choose a mode

Situation Mode Example
You are about to push your own changes Batch Quiz me on this branch before I push.
You are about to approve or merge someone else's PR Review Review PR 64.
You need to learn a codebase or rehearse its architecture System Help me learn billing-api.
You need to absorb a document, page, or topic Study Study docs/rfc.md.
You want to review due cards or explore one concept deeply Drill Drill me on cache eviction.

Invocation names differ only by client:

Client Form
Claude Code /explaingate <mode> <scope>
Codex $explaingate <mode> <scope>

Batch: understand your changes before pushing

Use batch mode for work you authored, including AI-assisted changes.

/explaingate
$explaingate batch main..HEAD
Quiz me on this branch before I push.

ExplainGate reads the diff and enough surrounding code to ask about:

  • how the change works;
  • why this approach was chosen;
  • where the behavior starts and stops;
  • what would break first if the change were wrong.

The default is about four questions. A genuine pass writes a marker tied to the current HEAD; the next commit makes that marker stale automatically. The visual artifact shows the change mechanism, tradeoffs, boundaries, blast radius, and demonstrated answers. An unfinished quiz still gets an honest developing artifact, but no pass marker.

Review: understand someone else's pull request

Use review mode before approving or merging a PR.

/explaingate review 64
$explaingate review https://github.com/example/project/pull/64

ExplainGate reads the PR description, changed files, and diff. Questions emphasize comprehension and judgment: the riskiest hunk, missing tests, hidden behavior changes, blast radius, and the review comment you would leave.

A pass is tied to the PR number and remains valid for 24 hours. Run the session inside the repository clone if you want it to open that clone's merge or approval gate. The artifact turns the PR flow, risks, missing evidence, scoped verdict, and review-ready observations into a visual review record.

System: learn a codebase for real

Use system mode for onboarding, architecture preparation, or catching your understanding up to a system built with substantial AI assistance.

/explaingate system billing-api
$explaingate system billing-api card

ExplainGate surveys the entry points, dependencies, deployment configuration, tests, and recent history. It builds a syllabus at three levels:

  1. Identity: what the system is, what it uses, and where it runs.
  2. Flow: how requests, data, and state move through it.
  3. Judgment: why key decisions were made, their limits, and likely failure modes.

Sessions cover two to four concepts in about 15–20 minutes. Progress is saved so the next session resumes with the weakest concept. When you are ready, ExplainGate can conduct a mock architecture walkthrough as a final exam.

Adding card produces a one-page system card with an elevator explanation, mechanism diagram, likely questions, scoped decisions, and glossary. It is rendered as a private, portable visual artifact by default.

Study: absorb a document, webpage, or topic

Use study mode when reading alone is not enough.

/explaingate study docs/rfc.pdf
$explaingate study https://example.com/design-note
$explaingate card retry-strategies

The source can be a local file, webpage, pasted text, or topic. ExplainGate distills four to eight important claims, mechanisms, consequential numbers, scope limits, and applications to your work. It quizzes you, teaches gaps, then saves surviving concepts as cards with source links.

The artifact organizes the concept map, claims and evidence, numbers, boundaries, applications, and corrected answers into one visual study page.

Long sources are split across sessions instead of being superficially covered all at once.

Drill: retain or deepen knowledge

A standard drill serves three to five cards whose due date has arrived.

/explaingate drill
$explaingate drill

Questions are always variants, never copies of the card's original question. A clean recall advances the card through 1, 3, 7, 21, and 45-day intervals. A miss returns it to tomorrow and teaches the gap.

Afterward, the artifact shows the retrieval path, clean recalls, misses, newly exposed gaps, corrected answers, and next due dates.

Name a concept for a focused descent:

/explaingate drill cache-eviction
$explaingate drill cache-eviction

The questions move from recall to mechanism, edges, application, and connections with other concepts. The descent stops after demonstrating new depth or finding a gap worth teaching and carding.

Cards and artifacts

The scope makes card unambiguous:

Command Meaning
card <topic> Research or study that topic and create spaced-repetition cards
system <name> card Generate a one-page system card
Bare card Regenerate the current batch summary card and visual artifact without another quiz or pass marker
artifact Regenerate only the current or most recent visual artifact without a quiz or pass marker

Every completed mode renders a self-contained HTML artifact. Learn how it works and how to share it safely in Visual artifacts.

Next: learn what the hooks store and enforce in Gates and local data.