psyclaw 0.27.23 → 0.28.1

package/vendor/ars/deep-research/references/socratic_questioning_framework.md

@@ -0,0 +1,232 @@
+# Socratic Questioning Framework — Academic Research Application
+
+## Overview
+
+Socratic Questioning originates from the dialogue-based teaching method of the ancient Greek philosopher Socrates. Its core is not about imparting knowledge, but about helping the interlocutor discover blind spots, contradictions, and deep-seated assumptions in their own thinking through systematic questioning. This framework applies this method to the context of academic research guidance.
+
+---
+
+## 6 Core Question Types
+
+### Type 1: Clarification Questions
+
+**Purpose**: Ensure the interlocutor truly understands the concepts they are using
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| What do you mean by "X"? | When the user uses vague or polysemous terms |
+| Can you give a specific example? | When abstract descriptions need concretization |
+| Can you put it another way? | To confirm mutual understanding |
+| How is this different from Y? | To distinguish similar concepts |
+| What does X include? What does it exclude? | To define scope |
+
+### Type 2: Probing Assumptions
+
+**Purpose**: Reveal hidden premises and assumptions
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| What are you assuming? | When the user's reasoning skips certain premises |
+| Is this assumption justified? | When the reasonableness of a premise needs verification |
+| What if this assumption doesn't hold? | To test the robustness of reasoning |
+| Why do you take this for granted? | When the user is overconfident about a premise |
+| Does anyone disagree with this premise? Why? | To introduce different perspectives |
+
+### Type 3: Probing Rationale and Evidence
+
+**Purpose**: Probe the basis and evidence foundation of reasoning
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| What is your evidence? | When the user makes unsupported assertions |
+| How do you know this is true? | When distinguishing facts from opinions is needed |
+| What other evidence supports or contradicts this? | To broaden the evidence horizon |
+| Is this evidence sufficient? | To evaluate the match between evidence and conclusions |
+| How would you respond to doubts about data reliability? | To test the solidity of evidence |
+
+### Type 4: Questioning Viewpoints and Perspectives
+
+**Purpose**: Introduce alternative viewpoints to break the limitations of a single perspective
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| What would this look like from another perspective? | When the user is stuck in a single viewpoint |
+| What would someone who disagrees say? | To introduce opposing thinking |
+| If you were X (a different stakeholder), how would you see this? | Multi-stakeholder analysis |
+| Why might others see this differently? | To understand the sources of viewpoint differences |
+| Does another discipline frame this phenomenon differently? | Interdisciplinary thinking |
+
+### Type 5: Probing Implications and Consequences
+
+**Purpose**: Explore the logical consequences and practical impacts of reasoning
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| If this conclusion is correct, what does it imply? | To trace logical implications |
+| What are the practical consequences? | To connect theory to practice |
+| What are the best and worst case scenarios? | To assess impact range |
+| Who benefits? Who is harmed? | Ethical dimension thinking |
+| Where does this trend lead in the long run? | Extended thinking |
+
+### Type 6: Questioning the Question
+
+**Purpose**: Examine whether the question itself is worth asking and whether the framing is correct
+
+| Question Pattern | Usage Context |
+|---------|---------|
+| Why does this question matter? | To return to research motivation |
+| Is there a better way to frame this question? | To optimize question formulation |
+| What is the question behind this question? | To excavate deeper concerns |
+| What if we're asking the wrong question? | Fundamental reflection |
+| What preconditions must exist to answer this? | To examine answerability |
+
+---
+
+## Academic Research Question Banks
+
+### Research Question Clarification
+
+1. Are you asking a "whether" question, a "how much" question, or a "why" question?
+2. Can you state your research question in a single sentence? If it takes more than one sentence, it may need splitting.
+3. If you could run only one statistical test or interview one person, what would it be?
+4. Does your question imply an expected answer? If so, is that a question or a hypothesis?
+5. Five years from now, what do you hope this research will have answered?
+
+### Methodology Probing
+
+1. Did you choose this method because it best fits your question, or because you're most familiar with it?
+2. What alternative explanations can your design rule out? What can't it?
+3. Would your conclusions hold with half your expected sample size?
+4. Is your instrument actually measuring what you intend to measure? (validity)
+5. Would another researcher get the same results using the same method? (reliability)
+
+### Literature Positioning
+
+1. What is the dominant narrative in this field? Are you supporting or challenging it?
+2. If your research is a conversation, who are you responding to?
+3. Are there decade-old studies now considered wrong? What does that tell you?
+4. Do your cited sources share a common blind spot?
+5. Have you deliberately searched for literature that contradicts your view?
+
+### Analytical Reasoning
+
+1. Is what you observe correlation or causation? How do you distinguish them?
+2. Where does your analytical framework come from? Has it been criticized?
+3. If you gave your data to another researcher without your hypothesis, what would they see?
+4. Are there outliers that don't fit your theory? How do you handle them?
+5. Have you tried to disprove your own hypothesis?
+
+### Conclusions and Limitations
+
+1. Does your conclusion go beyond what your evidence supports?
+2. To what extent can your findings be generalized? Where do they not apply?
+3. If you had to add a section "I might be wrong because...", what would it say?
+4. Is your limitations section a genuine reflection or a formality?
+5. What would future researchers need to verify or refute your conclusions?
+
+### Contribution and Significance
+
+1. If your research were never published, what would academia and practice lose?
+2. Can you explain why your research matters in three sentences to a non-expert?
+3. Is your research "filling a gap" or "changing understanding"? These differ in value.
+4. Will your research still be cited in ten years? Why?
+5. How does your research connect to the most pressing issues in society today?
+
+---
+
+## Questioning Strategies
+
+### Strategy 1: Funnel Strategy
+From open to focused, progressively narrowing scope.
+
+```
+Q1: "What aspects of higher education interest you?" (Open)
+Q2: "You mentioned quality assurance — what part of QA makes you most curious?" (Focused)
+Q3: "Where do you think the problem lies with accreditation indicator design?" (More focused)
+Q4: "So what you're asking is: can current accreditation indicators truly reflect teaching quality?" (Precise)
+```
+
+### Strategy 2: Mirror Strategy
+Restate the user's words, then follow up.
+
+```
+User: "I think declining birth rates will cause many private universities to close down"
+Mentor: "You think there's a direct causal relationship between declining birth rates and private university closures. Do you think there might be other mediating factors in this causal chain? For example, are there some private universities that have actually grown against the trend despite declining birth rates?"
+```
+
+### Strategy 3: Counterfactual Strategy
+Imagine the opposite situation to test reasoning.
+
+```
+User: "Online learning has improved learning outcomes"
+Mentor: "If a university that completely didn't adopt online learning had better student grades and satisfaction than those that did, how would you explain that? Would this change your research question?"
+```
+
+### Strategy 4: Analogy Strategy
+Use similar problems from other domains to inspire thinking.
+
+```
+User: "I want to research the effectiveness of university mergers"
+Mentor: "Research on corporate mergers and acquisitions shows that most M&A actually damages rather than improves performance in the short term. Do you think university mergers might have a similar pattern? What are the key differences between university mergers and corporate M&A?"
+```
+
+### Strategy 5: Strategic Silence
+Sometimes the best follow-up is waiting, giving the user space to think.
+
+```
+User: "I think... maybe... actually I'm not sure"
+Mentor: "Take your time. You just said 'actually I'm not sure' — what exactly are you unsure about? Is it the question itself, or your position on the question?"
+```
+
+---
+
+## Design Alignment with AI Learning Guidance Engines
+
+The dialogue design principles of this framework are consistent with AI learning guidance engines:
+
+| Design Principle | Socratic Mentor | ai-study-learn-engine |
+|---------|-----------------|----------------------|
+| Brief feedback | 1-2 sentences of affirmation/restatement | 1-2 sentences of indicator performance feedback |
+| Data citation | Hint at literature directions | Cite specific indicator data |
+| Focused follow-up | 1-2 precise questions | 1 learning guidance question |
+| Response length limit | 200-400 words | 200-300 words |
+| Insight extraction | [INSIGHT: ...] | [LEARNING: ...] |
+| Convergence mechanism | 15-round limit | 10-round limit |
+
+This consistency ensures a coherent experience when users switch between different tools.
+
+---
+
+## SCR Overlay Protocol
+
+The SCR (State-Challenge-Reflect) overlay works ON TOP of existing Socratic questioning. It does not replace any existing mechanism; it adds a commitment-tracking layer that deepens the learning impact.
+
+### Mapping to Socratic Functions
+
+| SCR Phase | Socratic Function | Timing | Purpose |
+|-----------|------------------|--------|---------|
+| **State** (表態) | Clarifying + Probing | Before presenting data/evidence | Collect user's prediction or self-assessment |
+| **Challenge** (挑戰) | Structuring + Challenging | After commitment collected | Present information that tests the commitment |
+| **Reflect** (反思) | Probing + Structuring | After divergence revealed | Guide user to self-explain the gap |
+
+### Design Constraints
+1. The user never sees the words "SCR", "commitment gate", or "divergence reveal"
+2. The experience feels like a natural Socratic dialogue that happens to ask for predictions before showing data
+3. The mechanism is invisible; the learning is visible
+4. Commitment questions should feel like natural warm-up questions, not formal assessments
+5. If the user's commitment turns out to be accurate, acknowledge it and move on — no need to force divergence where none exists
+
+### Integration with Convergence Signals
+The new S5/C5 (Self-Calibration) signal tracks whether the user's commitments become more accurate over the dialogue. This signal:
+- Strengthens convergence when present (user is both understanding AND self-aware)
+- Does NOT block convergence when absent (understanding can exist without perfect self-calibration)
+- Provides valuable coaching feedback at dialogue end
+
+---
+
+## References
+
+- Paul, R., & Elder, L. (2007). *Critical Thinking: The Art of Socratic Questioning*. Journal of Developmental Education, 31(1), 36-37.
+- Overholser, J. C. (1993). Elements of the Socratic method: I. Systematic questioning. Psychotherapy, 30(1), 67-74.
+- Burbules, N. C. (1993). *Dialogue in Teaching: Theory and Practice*. Teachers College Press.
+- Copeland, M. (2005). *Socratic Circles: Fostering Critical and Creative Thinking in Middle and High School*. Stenhouse Publishers.

package/vendor/ars/deep-research/references/source_quality_hierarchy.md

@@ -0,0 +1,188 @@
+# Source Quality Hierarchy — Evidence Grading Framework
+
+## Purpose
+Systematic framework for grading evidence quality, used by the source_verification_agent and bibliography_agent.
+
+## Evidence Pyramid (7 Levels)
+
+```
+         ╱╲
+        ╱ I ╲        Systematic Reviews / Meta-Analyses
+       ╱──────╲
+      ╱  II    ╲     Randomized Controlled Trials
+     ╱──────────╲
+    ╱   III      ╲   Controlled Studies (non-randomized)
+   ╱──────────────╲
+  ╱    IV          ╲  Case-Control / Cohort Studies
+ ╱──────────────────╲
+╱     V              ╲  Systematic Reviews of Descriptive Studies
+╱──────────────────────╲
+╱      VI                ╲  Single Descriptive / Qualitative Studies
+╱──────────────────────────╲
+╱       VII                  ╲  Expert Opinion / Committee Reports
+╱──────────────────────────────╲
+```
+
+## Detailed Level Descriptions
+
+### Level I: Systematic Reviews & Meta-Analyses
+**Weight**: Highest
+**Description**: Rigorous synthesis of all available evidence using predefined, systematic methods.
+**Characteristics**:
+- Pre-registered protocol (PROSPERO or similar)
+- Comprehensive search across multiple databases
+- Explicit inclusion/exclusion criteria
+- Quality assessment of included studies
+- Statistical pooling (meta-analysis) when appropriate
+- PRISMA reporting guidelines followed
+
+**Trusted Sources**: Cochrane Library, Campbell Collaboration, JBI Evidence Synthesis
+
+**Caveats**: Quality depends on included studies ("garbage in, garbage out"); may be outdated if field moves fast.
+
+### Level II: Randomized Controlled Trials (RCTs)
+**Weight**: Very High
+**Description**: Experimental studies with random allocation to intervention/control groups.
+**Characteristics**:
+- Random assignment
+- Control/comparison group
+- Blinding (single, double, or triple)
+- Pre-registered protocol
+- Adequate sample size
+- Intention-to-treat analysis
+
+**Caveats**: Not always feasible (especially in social science/education); ethical constraints; external validity concerns.
+
+### Level III: Controlled Studies Without Randomization
+**Weight**: High
+**Description**: Quasi-experimental designs with comparison groups but no randomization.
+**Characteristics**:
+- Comparison group present
+- Pre-post measurements
+- Attempts to control confounds
+- Larger samples than case studies
+
+**Examples**: Difference-in-differences, propensity score matching, regression discontinuity.
+
+**Caveats**: Selection bias risk; confounding variables harder to control.
+
+### Level IV: Case-Control & Cohort Studies
+**Weight**: Moderate-High
+**Description**: Observational studies tracking groups over time or comparing cases to controls.
+**Characteristics**:
+- Longitudinal (cohort) or retrospective (case-control)
+- Natural variation, no researcher intervention
+- Large samples possible
+- Real-world context
+
+**Caveats**: Cannot establish causation; confounders possible; recall bias (case-control).
+
+### Level V: Systematic Reviews of Descriptive/Qualitative Studies
+**Weight**: Moderate
+**Description**: Rigorous synthesis of qualitative or descriptive research.
+**Characteristics**:
+- Systematic search and selection
+- Quality appraisal of included studies
+- Meta-synthesis or meta-ethnography techniques
+- Transparent methods
+
+**Caveats**: Quality limited by included studies; interpretive layer adds subjectivity.
+
+### Level VI: Single Descriptive or Qualitative Studies
+**Weight**: Low-Moderate
+**Description**: Individual case studies, ethnographies, surveys, descriptive analyses.
+**Characteristics**:
+- In-depth, context-rich
+- Exploratory or descriptive purpose
+- Small samples typical
+- Thick description
+
+**Caveats**: Limited generalizability; researcher subjectivity; no causal claims warranted.
+
+### Level VII: Expert Opinion & Committee Reports
+**Weight**: Lowest
+**Description**: Position papers, editorials, committee reports, guidelines based on expert consensus.
+**Characteristics**:
+- Based on expertise and experience
+- Often integrates multiple evidence types informally
+- May reflect institutional or ideological positions
+
+**Caveats**: Not empirically tested; potential bias; "authority" ≠ "evidence."
+
+## Grading Rubric
+
+Each source is assessed on **two distinct axes** that the columns below combine. Conflating them caps strong interpretive and qualitative work at a low overall grade no matter how excellent it is within its own tradition.
+
+- **Study-design level** — where the design sits on the experimental-to-descriptive ladder (the 7-level pyramid above). This is absolute and field-neutral: a single qualitative case study is Level VI whether it appears in medicine or history.
+- **Fitness for claim within a discipline** — whether the source is excellent *by its field's norms for the specific claim being made*. A primary archival source can be Level VI design evidence and at the same time the gold-standard evidence its field offers for an interpretive claim.
+
+The **Evidence Level** criterion below grades *fitness*, not raw design level. A source earns Grade A on Evidence Level when its study-design level meets or exceeds **its own field's gold standard** (see the Field-Specific Adjustments table below), not only when it reaches Level I-II. So humanities work at Level VI, where Level VI *is* the field's gold standard, can score Grade A on this criterion. The other five criteria are field-neutral.
+
+| Criterion | Grade A (Excellent) | Grade B (Good) | Grade C (Adequate) | Grade D (Weak) | Grade F (Unacceptable) |
+|-----------|-------|-------|-------|-------|-------|
+| Evidence Level | Meets/exceeds the field's gold standard for the claim | One level below the field's gold standard | Two levels below | Well below field norm | Unclassifiable or fundamentally unfit for the claim |
+| Peer Review | Rigorous peer review | Standard peer review | Editorial review | No formal review | Self-published |
+| Methodology | Exemplary, replicable | Sound, described | Adequate | Questionable | Absent/flawed |
+| Sample/Data | Large, representative | Adequate | Limited but justified | Small, convenience | Unspecified |
+| Currency | < 3 years | 3-5 years | 5-10 years | > 10 years | Outdated for topic |
+| Conflicts | None declared or detected | Minor, disclosed | Moderate, disclosed | Undisclosed potential | Clear undisclosed conflict |
+
+> "Currency" is claim-relative: a foundational or historical source is not penalized for age when the claim is about that source itself or its period. Apply the age bands only when recency bears on the claim (e.g., empirical state-of-the-field assertions).
+
+### Overall Source Grade
+
+The overall grade reflects **fitness for the claim**, not raw study-design level. A source whose design level is low (e.g., a Level VI primary source) can still earn an overall Grade A when it is excellent by its field's norms for the claim it supports.
+
+**Aggregation rule.** Grade the six criteria above (each A-F), then combine:
+
+1. **Integrity floor.** If **Conflicts** is F (clear undisclosed conflict), or **Peer Review** is F in a field whose Field-Specific Adjustments row (below) treats formal review as the norm, the overall grade is capped at D regardless of the other criteria. Integrity failures are not outweighed by strength elsewhere.
+2. **Base grade.** Otherwise the overall grade is the **median** of the six criterion grades (on the A=4 … F=0 scale, rounding down on a tie between two adjacent grades).
+3. **Fitness adjustment.** Raise the base grade by one step when **Evidence Level** (fitness) is Grade A — a source that is gold-standard for its field reaches overall A even when field-neutral criteria like Currency or Sample/Data sit lower. Do not apply this step if **Methodology** is F (a fundamentally flawed method is not rescued by field fit). Never raise past A.
+
+So an interpretive study that is gold-standard within its discipline reaches overall Grade A, while an integrity-compromised (step 1) or methodologically broken (step 3 proviso) source does not, in any field.
+
+**Overall grade meaning:**
+
+- **A**: Use as primary evidence
+- **B**: Use as supporting evidence
+- **C**: Use with explicit caveats
+- **D**: Use only if no better source; acknowledge weakness
+- **F**: Do not use; cite only if critiquing
+
+## Field-Specific Adjustments
+
+Not all fields use the same evidence hierarchy. Adjust expectations:
+
+| Field | Gold Standard | Common Level | Notes |
+|-------|--------------|-------------|-------|
+| Medicine/Health | Level I-II (RCTs, meta-analyses) | Level I-III | Evidence-based medicine tradition |
+| Education | Level III-IV (quasi-experimental) | Level IV-VI | Randomization often impractical |
+| Social Science | Level III-V | Level IV-VI | Mixed methods common |
+| Policy | Level IV-V + VII (expert panels) | Level V-VII | Context-dependent; expert opinion valued |
+| Humanities | Level VI (primary sources) | Level VI-VII | Different epistemology; "evidence" means different things |
+| Technology | Level III + industry reports | Level V-VII | Fast-moving; peer review lags reality |
+
+## Predatory Publication Indicators
+
+### Red Flags Checklist
+- [ ] Aggressive email solicitation to submit
+- [ ] Acceptance within 72 hours of submission
+- [ ] No identifiable editorial board (or fake names)
+- [ ] Not indexed in Scopus, Web of Science, or PubMed
+- [ ] Not member of COPE (Committee on Publication Ethics)
+- [ ] Not listed in DOAJ (Directory of Open Access Journals)
+- [ ] Excessively broad scope ("International Journal of Everything")
+- [ ] Fake or inflated impact metrics
+- [ ] Poor grammar/spelling on journal website
+- [ ] APC (article processing charge) suspiciously low (< $200 for full OA)
+- [ ] Editorial office in different country from stated location
+- [ ] No retraction policy or ethics guidelines
+
+### Verification Resources
+- Beall's List (unofficial, but useful starting point)
+- Cabell's Predatory Reports (subscription-based)
+- DOAJ (whitelist of legitimate OA journals)
+- COPE member directory
+- Scopus Source List
+- Journal Citation Reports (Clarivate)
+- Think. Check. Submit. (thinkchecksubmit.org)

package/vendor/ars/deep-research/references/systematic_review_protocol.md

@@ -0,0 +1,95 @@
+# Systematic Review Mode — Full Protocol
+
+Full PRISMA-compliant systematic literature review with optional meta-analysis. This mode extends the standard 6-phase pipeline with specialized agents for risk of bias assessment (RoB 2, ROBINS-I) and quantitative synthesis.
+
+See `agents/risk_of_bias_agent.md` and `agents/meta_analysis_agent.md` for detailed agent definitions.
+See `references/systematic_review_toolkit.md` for the Cochrane/PRISMA/GRADE reference guide.
+
+## 5-Phase Pipeline
+
+```
+User: "Systematic review of [topic]" / "Meta-analysis of [topic]"
+     |
+=== Phase 1: SCOPING (Generates Protocol, not just RQ) ===
+     |
+     |-> [research_question_agent] -> PICOS-formatted RQ
+     |   - Population, Intervention, Comparator, Outcome, Study design
+     |   - Explicit eligibility criteria (inclusion/exclusion)
+     |
+     |-> [research_architect_agent] -> Systematic Review Protocol
+     |   - Protocol follows PRISMA-P 2015 (templates/prisma_protocol_template.md)
+     |   - Pre-specified subgroup analyses and sensitivity analyses
+     |   - Risk of bias tool selection (RoB 2 / ROBINS-I)
+     |   - Meta-analysis feasibility pre-assessment
+     |
+     +-> [devils_advocate_agent] -- CHECKPOINT 1
+         - PICOS specificity check
+         - Search strategy comprehensiveness
+         - Protocol completeness
+         - Verdict: PASS / REVISE
+     |
+     ** User confirmation of protocol before Phase 2 **
+     |
+=== Phase 2: INVESTIGATION (PRISMA-Compliant Search + RoB) ===
+     |
+     |-> [bibliography_agent] -> PRISMA Flow Diagram + Source Corpus
+     |   - Search >= 2 databases with documented strategy
+     |   - Dual-pass screening (title/abstract -> full text)
+     |   - PRISMA 2020 flow diagram with counts at each stage
+     |   - Excluded studies with reasons documented
+     |
+     |-> [source_verification_agent] -> Verified Sources
+     |   - Standard verification + predatory journal screening
+     |
+     +-> [risk_of_bias_agent] -> RoB Assessment
+         - Per-study domain assessment with signaling questions
+         - Traffic-light summary table across all studies
+         - Distribution summary (% Low / Some Concerns / High)
+     |
+=== Phase 3: ANALYSIS (Meta-Analysis or Narrative Synthesis) ===
+     |
+     |-> [meta_analysis_agent] -> Quantitative or Narrative Synthesis
+     |   - Feasibility assessment (pool or not?)
+     |   - If feasible: effect size calculation, forest plot data,
+     |     heterogeneity (I-squared, Q, tau-squared), subgroup/sensitivity analyses
+     |   - If not feasible: structured narrative synthesis (SWiM)
+     |   - GRADE certainty of evidence for each outcome
+     |
+     |-> [synthesis_agent] -> Qualitative Themes + Gap Analysis
+     |   - Thematic synthesis across studies
+     |   - Integration with quantitative findings
+     |
+     +-> [devils_advocate_agent] -- CHECKPOINT 2
+         - Cherry-picking check
+         - Heterogeneity explanation adequacy
+         - GRADE assessment validity
+         - Verdict: PASS / REVISE
+     |
+=== Phase 4: COMPOSITION ===
+     |
+     +-> [report_compiler_agent] -> PRISMA 2020 Report
+         - Uses templates/prisma_report_template.md
+         - All 27 PRISMA items mapped to sections
+         - Study characteristics table
+         - Risk of bias summary table
+         - Forest plot data (if meta-analysis)
+         - GRADE Summary of Findings table
+     |
+=== Phase 5: REVIEW (Parallel) ===
+     |
+     |-> [editor_in_chief_agent] -> Editorial Verdict
+     |-> [ethics_review_agent] -> Ethics Clearance
+     +-> [devils_advocate_agent] -- CHECKPOINT 3
+     |
+=== Phase 6: REVISION ===
+     |
+     +-> [report_compiler_agent] -> Final PRISMA Report
+```
+
+## Checkpoint Rules
+
+1. All standard checkpoint rules apply (see SKILL.md Checkpoint Rules)
+2. **Protocol must be registered** (or registration recommended) before Phase 2
+3. **Risk of bias must be completed for all studies** before Phase 3
+4. **GRADE assessment required** for every pooled outcome
+5. **PRISMA checklist compliance** verified in Phase 5