agentleFS
VladTheProgrammerVladTheProgrammer/claude-asimov/.claude/skills/questions/SKILL.md

questions

Skill0 starsChanged 4 months agoMITView on GitHub

Generate exhaustive understanding questions for a task using parallel analytical lenses. Usage: /questions {task-name} {file-paths...}

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If no file paths are provided, ask the user for at least one file containing the task description.

    line 10
  2. Distinctive:

    Read every file path provided.

    line 14
  3. Very specific:

    Use the Agent tool with subagent_type: "question-finder" for all four.

    line 28
  4. Distinctive:

    After all four agents complete:

    line 150
  5. Distinctive:

    If a sub-category produced no questions, omit it (don't leave empty sections).

    line 259
  6. Distinctive:

    Delete all fragment files.

    line 261

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Parse the user's input:

  • First argument is the task name (used for the output directory, e.g., offline-sync-bugfix)
  • Remaining arguments are file paths to the task description and/or research context (*.md files)

If no file paths are provided, ask the user for at least one file containing the task description.

Phase 1 — Read all input files

Read every file path provided. You need their content to build the context summary that frames each agent's work.

Build a task brief — a compact summary (max ~500 words) capturing:

  • What the task is (feature, bugfix, refactor, etc.)
  • Key requirements or constraints mentioned
  • Technical areas referenced
  • Any open questions or ambiguities already noted

This brief is passed to every agent alongside the file paths.

Phase 2 — Spawn parallel question-finder agents

Spawn four question-finder agents in parallel, one per lens. Each receives the task brief and file paths.

Use the Agent tool with subagent_type: "question-finder" for all four.


Lens 1: User & Stakeholder Questions

task_name: {task-name}
lens_name: User & Stakeholder
lens_methodology: (below)
research_paths: {all file paths}
task_brief: {task brief from Phase 1}

Methodology — Schein's Humble Inquiry + Bloom's Remember/Understand + ORID Objective/Decisional:

Generate questions that only a human with domain knowledge or decision-making authority can answer. These establish the factual foundation and success criteria before any technical work begins.

Sub-categories:

  1. Intent & Motivation — Why does this task exist? What outcome matters to the user/business? What triggered it? (Technique: ask "what outcome do we need?" before "how do we build it?" — McKinsey reframing)
  2. Scope & Boundaries — What is explicitly in scope? What is explicitly out? Where are the ambiguous boundaries? (Technique: for every stated requirement, ask what's adjacent but excluded)
  3. Constraints & Priorities — What non-negotiable limits exist (time, compatibility, performance, platform)? If trade-offs are needed, what wins? (Technique: forced-rank questions — "If you could only have two of these three, which two?")
  4. Acceptance & Verification — What does "done" look like concretely? How will a human verify correctness? What's the minimum viable version vs. the ideal version? (Technique: behavioral anchoring — "Describe a specific scenario where this works correctly")
  5. User & Stakeholder Context — Who is affected by this change? Who has opinions that matter? Are there downstream teams or processes that depend on the current behavior? (Technique: SMM team-member model — map who knows what)

Lens 2: Codebase Research Questions

task_name: {task-name}
lens_name: Codebase Research
lens_methodology: (below)
research_paths: {all file paths}
task_brief: {task brief from Phase 1}

Methodology — SMM Task/Technology Models + Diagnostic Inquiry:

Generate questions answerable by exploring the existing codebase. These map the technical landscape so implementation decisions are grounded in reality.

Sub-categories:

  1. Architecture & Patterns — How is the affected area structured today? What design patterns does it use? What conventions exist that new code should follow? (Technique: Cannon-Bowers equipment/task model — map the technology and procedures)
  2. Dependencies & Coupling — What modules, services, or components call into or are called by the affected code? What shared state, events, or data contracts exist? (Technique: ask about every direction of coupling — upstream callers, downstream callees, shared state, event listeners)
  3. Data & State Flow — What data enters this area, how is it transformed, and where does it go? What mutations happen? What invariants must hold? (Technique: trace the data lifecycle from entry to persistence)
  4. Error Handling & Edge Cases — How does the current code handle failures? What happens with null/empty/malformed input? Are there retry mechanisms, fallbacks, or circuit breakers? (Technique: ask about the unhappy path for every happy-path assumption)
  5. Testing & Observability — What test coverage exists? What testing strategy is used (unit, integration, e2e)? What logging, metrics, or monitoring would surface problems? (Technique: ask what would break detectably vs. silently)
  6. Configuration & Environment — What feature flags, environment variables, build variants, or runtime settings affect this area? What differs between dev/staging/prod? (Technique: list every external input to the code's behavior)

Lens 3: External Research Questions

task_name: {task-name}
lens_name: External Research
lens_methodology: (below)
research_paths: {all file paths}
task_brief: {task brief from Phase 1}

Methodology — SMM Equipment/Technology Models + Reference Class Forecasting:

Generate questions answerable through web research, documentation, or domain expertise. These provide the broader context that the codebase alone can't reveal.

Sub-categories:

  1. Standards & Specifications — What formal standards, protocols, or specs govern this area? Are there RFCs, W3C specs, platform guidelines, or regulatory requirements that apply? (Technique: for every technical choice, ask "is there a standard for this?")
  2. Library & Framework Documentation — What do the official docs say about the APIs, patterns, or features we'll use? Are there known limitations, deprecations, or migration paths? What versions matter? (Technique: ask about the gap between "how we use it" and "how the docs say to use it")
  3. Precedent & Patterns — How have other projects solved this problem? Are there established architectural patterns for this type of task? What are the known trade-offs? (Technique: Reference Class Forecasting — "what happened in comparable projects?")
  4. Platform & Environment — What platform-specific behaviors, limitations, or requirements apply? What OS/browser/device differences matter? What are the deployment constraints? (Technique: enumerate every platform target and ask what differs)
  5. Domain Knowledge — What domain-specific terminology, rules, or conventions apply that an implementer might not know? Are there regulatory, legal, or compliance considerations? (Technique: ask what a domain expert would consider obvious that a developer might miss)

Lens 4: Critical Analysis Questions

task_name: {task-name}
lens_name: Critical Analysis
lens_methodology: (below)
research_paths: {all file paths}
task_brief: {task brief from Phase 1}

Methodology — Pre-mortem (Klein) + Consider-the-Opposite (Lord et al.) + Socratic Questioning (Paul) + Dialectical Inquiry:

Generate questions that challenge assumptions, imagine failure, and explore alternatives. These are the highest-intensity questions — they synthesize understanding from the other three lenses and should be tackled last. They operate at Bloom's Analyze/Evaluate/Create levels.

Sub-categories:

  1. Assumption Audit — What assumptions are embedded in the task description that haven't been verified? What's taken for granted about user behavior, system state, data quality, or performance? (Technique: Socratic — for each stated requirement, ask "what must be true for this to hold?")
  2. Pre-mortem: Failure Scenarios — Imagine this task shipped and failed. What went wrong? What's the most likely failure mode? What's the most catastrophic? What's the sneakiest (fails silently)? (Technique: Klein's pre-mortem — "the project has failed; tell me why" generates ~30% more failure reasons than "what could go wrong?")
  3. Edge Cases & Boundary Conditions — What happens at the extremes? Zero items, maximum load, concurrent access, interrupted operations, stale data, clock skew, network partition? (Technique: for every "normal" scenario, ask about the boundary)
  4. Alternative Approaches — Is this the right solution to the right problem? What if we did the opposite? What's the simplest possible version? What would we do if we had half the time? Twice the time? (Technique: Consider-the-Opposite — "what would have to be true for a completely different approach to be better?")
  5. Trade-off Analysis — What are we gaining and giving up with this approach? What's the reversibility cost if this turns out wrong? Where are we optimizing for now vs. later? (Technique: Dialectical Inquiry — thesis/antithesis/synthesis on key design decisions)
  6. Second-order Effects — What changes does this force elsewhere? What future work does this enable or prevent? What technical debt does this create or resolve? (Technique: ask "and then what?" for each primary effect)

Phase 3 — Merge & structure

After all four agents complete:

  1. Glob docs/{task-name}/questions-*.md to find all fragment files
  2. Read every fragment
  3. Collect any CROSS-CUTTING themes from agent responses — weave relevant ones into the appropriate sections
  4. Combine all fragments into docs/{task-name}/questions.md with this structure:
# {Task Name} — Questions for Exhaustive Understanding

> Generated from: {list of input files}
>
> These questions are organized by who can answer them and in what order they
> should be pursued. The sequence follows ORID progressive intensity:
> establish facts first, then map the landscape, then broaden context,
> then challenge everything.

## Phase 1: Ask the User / Stakeholder

*Questions only a human with domain knowledge or authority can answer.
Establish the factual foundation before any technical exploration.*

### Intent & Motivation
- ...

### Scope & Boundaries
- ...

### Constraints & Priorities
- ...

### Acceptance & Verification
- ...

### User & Stakeholder Context
- ...

---

## Phase 2: Research the Codebase

*Questions answerable by exploring existing code.*

### Architecture & Patterns
- ...

### Dependencies & Coupling
- ...

### Data & State Flow
- ...

### Error Handling & Edge Cases
- ...

### Testing & Observability
- ...

### Configuration & Environment
- ...

---

## Phase 3: Research External Sources

*Questions requiring documentation, web research, or domain expertise.*

### Standards & Specifications
- ...

### Library & Framework Documentation
- ...

### Precedent & Patterns
- ...

### Platform & Environment
- ...

### Domain Knowledge
- ...

---

## Phase 4: Critical Analysis

*Highest-intensity questions. Tackle these after Phases 1-3 provide context.
These challenge assumptions and imagine failure.*

### Assumption Audit
- ...

### Pre-mortem: Failure Scenarios
- ...

### Edge Cases & Boundary Conditions
- ...

### Alternative Approaches
- ...

### Trade-off Analysis
- ...

### Second-order Effects
- ...
  1. Under each sub-category, list the questions as bullets. Preserve the parenthetical "why it matters" annotations.
  2. If a sub-category produced no questions, omit it (don't leave empty sections).
  3. Deduplicate questions that appear across fragments — keep the more specific version.
  4. Delete all fragment files.

Phase 4 — Report

Tell the user the output is at docs/{task-name}/questions.md and provide:

  • Total question count
  • Count per phase
  • Any notable cross-cutting themes the agents identified

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.