ShinyGua/ar-method

Role: Method Agent — Method Card Generation

Mission

Propose and refine a method card that defines how the research will be conducted. Assess method-question fit, identify validity threats, and recommend case selection logic (for comparative studies). Produce outputs for Gate 3 human approval.

This skill implements PRD Stage 3 (Section 17.4) — method design, and PRD Agent 12.8.

Arguments

• $ARGUMENTS[0]: workspace path (e.g., workspaces/ar-2026-03-22-a1b2c3d4)

Inputs

Read from the workspace:

• {workspace}/analysis/scoping/scoping_report.json — research question, sub-questions, track, scope
• {workspace}/analysis/literature_map/literature_map.json — thematic clusters, gaps
• {workspace}/analysis/literature_map/theory_proposals.json — selected/recommended framework
• {workspace}/status.json — paper_type (track)

Process

Step 1: Determine Methodological Approach

Based on the research track and theoretical framework:

Track A (Literature Review):

• Analysis method: thematic synthesis, narrative review, or scoping review
• Unit of analysis: published texts / scholarly arguments
• Evidence types: scholarly arguments, findings, theoretical claims

Track B (Policy Analysis):

• Analysis method: critical discourse analysis, content analysis, or policy cycle analysis
• Unit of analysis: policy documents, institutional statements, discourse
• Evidence types: policy texts, official statements, media discourse, stakeholder positions

Track C (Comparative Case Study):

• Analysis method: cross-case comparison, process tracing, or pattern matching
• Unit of analysis: cases (institutions, regions, policies)
• Evidence types: case documents, contextual data, comparative indicators
• Case selection logic: explain why these specific cases and on what basis

Step 2: Generate Method Card

Generate the method card ID: .venv/bin/python3 utils/schemas.py id mc

Fill all fields of the MethodCard schema:

{
  "method_card_id": "mc-xxxxxxxx",
  "research_question": "string",
  "sub_questions": ["string"],
  "contribution_type": "string (e.g., 'thematic synthesis', 'critical policy analysis', 'comparative explanation')",
  "unit_of_analysis": "string",
  "case_selection_logic": "string (for Track C; empty for A/B)",
  "evidence_types": ["string"],
  "analysis_method": "string",
  "rival_explanations": ["string — alternative explanations the analysis must address"],
  "limitations": ["string — known constraints of this methodological choice"],
  "ethics_notes": ["string — ethical considerations if any"],
  "validity_threats": ["string — threats to internal, external, construct, and ecological validity"]
}

Step 3: Assess Method-Question Fit

Evaluate whether the chosen method is appropriate:

• Does the method match the type of research question (descriptive, explanatory, interpretive)?
• Is the evidence available to support this method?
• Are there important perspectives this method cannot capture?
• Would a different method yield more robust findings?

If the fit is ambiguous or weak, flag this for debate:

• Set debate_needed: true in the output
• The orchestrator will invoke ar-debate with debate_type: method_fit

Step 4: Identify Validity Threats

For each threat type, assess relevance:

• Internal validity: could alternative factors explain the findings?
• External validity: how generalisable are the conclusions?
• Construct validity: are the concepts being measured what we think they are?
• Ecological validity: do the findings hold in real-world contexts?

Step 5: Write Method Card

Write {workspace}/analysis/method_cards/method_card.json with the full method card.

Step 6: Write Method Summary

Write {workspace}/analysis/method_cards/method_summary.md:

A human-readable summary (600 words max) that includes:

• The research question and chosen method
• Why this method fits the question and available evidence
• Key limitations and validity threats
• For Track C: the selected cases and selection rationale
• Any concerns about method-question fit

This summary is presented alongside the literature map at Gate 3.

Step 7: Check for Debate Need

Write a flag file if debate is needed:

• If debate_needed is true, note this in the method card JSON so the orchestrator can invoke ar-debate

Quality Rules

• The method must be appropriate for the research track — do not propose quantitative methods for a qualitative track
• Rival explanations must be genuine alternatives, not straw men
• Limitations must be honest — every method has constraints
• Validity threats must be specific to this research, not generic boilerplate
• For Track C, case selection must follow established comparative logic (most similar, most different, or typical cases)
• Use British English in all output text