Skip to content

ykorovko/dotagents / skills/how

Explain how code, a subsystem, or an architectural flow works. Use only when the user explicitly asks for a code walkthrough, runtime trace, ownership or layering explanation, or architecture critique.

How

Explore the codebase and give the user a working mental model of how something operates. Explain mechanics and architecture, not historical motivation. When why is also loaded, incorporate its evidence about historical motivation. Installation alone does not load or invoke another skill.

Treat this as a read-only investigation unless the user also asks for changes.

Choose the mode

  • Explain is the default. Trace the implementation and describe it clearly.
  • Critique applies only when the user asks about architectural problems, tradeoffs, or improvements. Explain the current design before judging it.

Explore

  1. State the scope you inferred from the request. If it is ambiguous, use the surrounding context and make the assumption visible.
  2. Find the real entry point. Trace callers, callees, data transformations, state changes, and side effects through the implementation. Read code rather than guessing from names.
  3. Identify the types, services, modules, or processes that carry the design. Note who owns each responsibility and where system boundaries sit.
  4. Check configuration, feature flags, generated code, persistence, queues, external APIs, and tests when they affect the flow.
  5. Follow the path until you can connect the trigger to its outcome without hand-waving. Record gaps instead of filling them with plausible behavior.

For a narrow question, investigate directly. For a large subsystem, split the exploration into independent slices only when the harness supports delegation and the user permits it. When delegating, read references/explorer-prompt.md and adapt its template for each distinct slice. Keep delegated work read-only and verify the findings against the code before using them.

Explain

Adapt the response to the question rather than forcing every section. A useful explanation usually contains:

  • Overview. What the subsystem does and where it fits.
  • Key concepts. Only the types and abstractions needed to follow the flow.
  • How it works. The trigger, sequence, data movement, decisions, and side effects, with concrete file:line references.
  • Where it lives. A short map of the files a maintainer would open first.
  • Gotchas and gaps. Surprising behavior, sharp edges, and anything you could not verify.

Use a small diagram only when several components or state transitions are materially easier to understand visually. Do not dump source code or turn the answer into an annotated file listing.

When several explorers contributed findings, read references/explainer-prompt.md before consolidating them. The coordinating agent may synthesize directly; a separate explainer is optional and requires the same delegation support and permission.

Critique

Explain the current design first. Then read references/critique-rubric.md and review only the lenses that apply.

Ground every finding in concrete code and state its practical cost. Separate:

  • Act on. Structural problems worth addressing now.
  • Consider. Real concerns whose cost or remedy is uncertain.
  • Noted. Low-priority tradeoffs or debt.
  • Dismissed. Suggestions rejected because they lack evidence, miss context, or express style preference.

Independent critics are optional when the harness supports them and the user permits delegation. When using them, read references/critic-prompt.md and give each critic that template plus the critique rubric. Keep their work read-only, reconcile their claims against the code rather than aggregating votes, and place accepted findings into the same Act on, Consider, or Noted buckets used above. Put rejected suggestions under Dismissed. An empty critique is valid when the architecture fits its needs.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall