psyclaw 0.27.22 → 0.28.0

package/vendor/ars/academic-paper/templates/literature_review_template.md

@@ -0,0 +1,135 @@
+# Literature Review Paper Template
+
+## Usage
+This template provides the skeleton for a thematic literature review paper that synthesizes existing research, identifies gaps, and proposes future directions.
+
+---
+
+# [Paper Title in Title Case]
+
+**Author(s):** [Author Name(s)]
+**Affiliation(s):** [Department, Institution]
+**Date:** [Date]
+
+---
+
+## Abstract
+
+[Background and rationale: 1-2 sentences.]
+[Purpose and scope of the review: 1 sentence.]
+[Method: 1 sentence on search strategy and source selection.]
+[Key findings from the synthesis: 2-3 sentences.]
+[Implications and identified gaps: 1-2 sentences.]
+
+**Keywords**: [keyword1], [keyword2], [keyword3], [keyword4], [keyword5]
+
+---
+
+## 1. Introduction
+
+### 1.1 Topic and Rationale
+[Why is this literature review needed? What makes it timely?]
+[2 paragraphs with citations]
+
+### 1.2 Scope and Boundaries
+[What is included and excluded? Time period? Disciplines? Geographies?]
+[1 paragraph]
+
+### 1.3 Review Methodology
+[Search strategy: databases, keywords, inclusion/exclusion criteria.]
+[Number of sources reviewed.]
+[1-2 paragraphs]
+
+### 1.4 Organization of the Review
+[Preview the thematic structure.]
+[1 paragraph]
+
+---
+
+## 2. [Theme 1: Descriptive Title]
+
+### 2.1 [Sub-Theme A]
+[Review literature on this sub-theme.]
+[2-3 paragraphs with citations]
+
+### 2.2 [Sub-Theme B]
+[Review literature on this sub-theme.]
+[2-3 paragraphs with citations]
+
+### 2.3 Summary of Theme 1
+[What does the literature collectively tell us about this theme?]
+[1 paragraph]
+
+---
+
+## 3. [Theme 2: Descriptive Title]
+
+### 3.1 [Sub-Theme A]
+[2-3 paragraphs with citations]
+
+### 3.2 [Sub-Theme B]
+[2-3 paragraphs with citations]
+
+### 3.3 Summary of Theme 2
+[1 paragraph]
+
+---
+
+## 4. [Theme 3: Descriptive Title]
+
+### 4.1 [Sub-Theme A]
+[2-3 paragraphs with citations]
+
+### 4.2 [Sub-Theme B]
+[2-3 paragraphs with citations]
+
+### 4.3 Summary of Theme 3
+[1 paragraph]
+
+---
+
+## 5. Cross-Cutting Synthesis
+
+### 5.1 Convergent Findings
+[What do the themes agree on? What patterns emerge across themes?]
+[1-2 paragraphs]
+
+### 5.2 Divergent Findings and Debates
+[Where do researchers disagree? What are the unresolved debates?]
+[1-2 paragraphs]
+
+### 5.3 Methodological Observations
+[What methods dominate? What methods are underused?]
+[1 paragraph]
+
+---
+
+## 6. Research Gaps and Future Directions
+
+### 6.1 Identified Gaps
+[List and discuss 3-5 specific gaps in the literature.]
+[1-2 paragraphs]
+
+### 6.2 Proposed Research Agenda
+[What should future researchers investigate? What methods should they use?]
+[1-2 paragraphs]
+
+---
+
+## 7. Conclusion
+
+### 7.1 Key Takeaways
+[Summarize the 3-5 most important insights from the review.]
+
+### 7.2 Implications for Practice and Policy
+[How should practitioners or policymakers use these insights?]
+
+---
+
+## AI Disclosure
+[Standard AI disclosure statement.]
+
+---
+
+## References
+[Complete reference list in selected citation format.]

package/vendor/ars/academic-paper/templates/policy_brief_template.md

@@ -0,0 +1,139 @@
+# Policy Brief Template
+
+## Usage
+This template provides the skeleton for an evidence-based policy brief targeting decision-makers. Policy briefs are shorter, more direct, and action-oriented than academic papers.
+
+---
+
+# [Policy Brief Title — Clear and Action-Oriented]
+
+**Author(s):** [Author Name(s)]
+**Affiliation:** [Institution]
+**Date:** [Date]
+**Target Audience:** [e.g., MOE officials, university administrators, legislators]
+
+---
+
+## Executive Summary
+
+[The policy problem in 1-2 sentences.]
+[Key evidence in 1-2 sentences.]
+[Primary recommendation in 1-2 sentences.]
+
+### Key Recommendations
+1. [Recommendation 1 — one sentence]
+2. [Recommendation 2 — one sentence]
+3. [Recommendation 3 — one sentence]
+
+---
+
+## 1. Background
+
+### 1.1 The Policy Problem
+[What is the problem? Who is affected? How severe is it?]
+[Use specific data to illustrate the problem.]
+
+### 1.2 Current Policy Context
+[What existing policies or regulations are relevant?]
+[What has already been tried?]
+
+### 1.3 Why Action is Needed Now
+[What makes this urgent? What happens if nothing changes?]
+[Include a compelling statistic or projection.]
+
+---
+
+## 2. Evidence Base
+
+### 2.1 Key Finding 1: [Title]
+[Present evidence clearly with citations.]
+[Include a figure or table if helpful.]
+
+### 2.2 Key Finding 2: [Title]
+[Present evidence clearly with citations.]
+
+### 2.3 Key Finding 3: [Title]
+[Present evidence clearly with citations.]
+
+### 2.4 International Comparisons *(if relevant)*
+[How do other countries/regions handle this issue?]
+[What can we learn from their experience?]
+
+---
+
+## 3. Policy Options Analysis
+
+### Option A: [Descriptive Name]
+[1-2 paragraph description of the option.]
+
+| Criterion | Assessment |
+|-----------|-----------|
+| **Effectiveness** | [High/Medium/Low — brief justification] |
+| **Feasibility** | [High/Medium/Low — brief justification] |
+| **Cost** | [High/Medium/Low — estimate if available] |
+| **Timeline** | [Short-term / Medium-term / Long-term] |
+| **Political Acceptability** | [High/Medium/Low] |
+
+### Option B: [Descriptive Name]
+[1-2 paragraph description.]
+
+| Criterion | Assessment |
+|-----------|-----------|
+| **Effectiveness** | [assessment] |
+| **Feasibility** | [assessment] |
+| **Cost** | [assessment] |
+| **Timeline** | [timeline] |
+| **Political Acceptability** | [assessment] |
+
+### Option C: [Descriptive Name]
+[1-2 paragraph description.]
+
+| Criterion | Assessment |
+|-----------|-----------|
+| **Effectiveness** | [assessment] |
+| **Feasibility** | [assessment] |
+| **Cost** | [assessment] |
+| **Timeline** | [timeline] |
+| **Political Acceptability** | [assessment] |
+
+---
+
+## 4. Recommendations
+
+### 4.1 Recommended Option
+[State the recommended option and justify the choice.]
+[1-2 paragraphs]
+
+### 4.2 Implementation Steps
+1. **Step 1** (Month 1-3): [action]
+2. **Step 2** (Month 4-6): [action]
+3. **Step 3** (Month 7-12): [action]
+4. **Step 4** (Year 2+): [action]
+
+### 4.3 Success Metrics
+| Metric | Baseline | Target | Timeline |
+|--------|----------|--------|----------|
+| [Metric 1] | [current value] | [target value] | [when] |
+| [Metric 2] | [current value] | [target value] | [when] |
+
+### 4.4 Risk Mitigation
+| Risk | Likelihood | Mitigation |
+|------|-----------|-----------|
+| [Risk 1] | [H/M/L] | [strategy] |
+| [Risk 2] | [H/M/L] | [strategy] |
+
+---
+
+## 5. Conclusion
+[1 paragraph restating the urgency and recommended action.]
+
+---
+
+## AI Disclosure
+[Standard AI disclosure statement.]
+
+## References
+[Complete reference list — keep concise for policy brief audience.]
+
+## Appendix: Methodology Note
+[Brief description of how the evidence was gathered and analyzed.]

package/vendor/ars/academic-paper/templates/revision_tracking_template.md

@@ -0,0 +1,199 @@
+# Revision Tracking Template
+
+## Usage
+
+Use this template to systematically track all reviewer comments and their resolutions during the revision process. Copy this template at the start of each revision round, fill in the paper information, then add one row per reviewer comment.
+
+This template works with both:
+- **Revision mode** (`revision` in SKILL.md): when you have a draft and structured reviewer feedback
+- **Revision Coach mode** (`revision-coach` in SKILL.md): when you have unstructured reviewer comments that need parsing first
+
+---
+
+## Paper Information
+
+| Field | Value |
+|-------|-------|
+| Paper Title | [title] |
+| Revision Round | [1 / 2] |
+| Date | [YYYY-MM-DD] |
+| Previous Decision | [Major Revision / Minor Revision] |
+| Target Journal | [journal name] |
+| Original Word Count | [N words] |
+| Revised Word Count | [N words] |
+
+---
+
+## Revision Tracking Table
+
+| # | Issue Description | Reviewer | Type | Section | Resolution Summary | Location of Change | Status | Reason (if not resolved) | Commitment Ledger |
+|---|-------------------|----------|------|---------|-------------------|-------------------|--------|--------------------------|-------------------|
+| 1 | [description] | [R1/R2/R3/DA] | [Major/Minor/Editorial] | [section] | [what was done] | [page/paragraph] | [status] | [if applicable] | See per-row nested ledger below (concern 1) |
+| 2 | [description] | [R1/R2/R3/DA] | [Major/Minor/Editorial] | [section] | [what was done] | [page/paragraph] | [status] | [if applicable] | See per-row nested ledger below (concern 2) |
+| 3 | [description] | [R1/R2/R3/DA] | [Major/Minor/Editorial] | [section] | [what was done] | [page/paragraph] | [status] | [if applicable] | _(empty — positive comment, no commitment)_ |
+
+**Per-row Commitment Ledger (nested-object shape, #268).** Each concern's commitments are authored as a single nested YAML block keyed by `concern_id` — one object per commitment, with `fulfillment_status` / `unfulfilled_rationale` nested **inside** the object. There are no separate parallel cells to keep aligned, so a dropped separator or mis-numbering can no longer desynchronize status from commitment.
+
+Placeholders use `<...>` (angle brackets) — replace each with a literal scalar. Do NOT use `[...]`: inside a YAML block square brackets parse as a flow sequence, so a half-filled `[R1-1]` becomes a one-element list, not the string `R1-1`. (The only real list here is `commitment_extracted: []`, the empty-list marker.)
+
+```yaml
+# concern 1 (multi-commitment example)
+- concern_id: <R1-1>
+  commitment_extracted:
+    - commitment_text: "<commitment 1 text>"
+      commitment_type: <add_experiment | add_analysis | add_clarification | add_citation | restructure | other>
+      required_evidence_type: <new_section | new_figure | new_table | new_citation | methods_paragraph | discussion_paragraph | prose_edit | acknowledgment_only | other>
+      fulfillment_status: <fulfilled | partial | not-fulfilled | explicitly-rejected-with-rationale>   # appended during revision execution
+      # unfulfilled_rationale: "..."  # required iff status is non-fulfilled; OMIT when fulfilled
+    - commitment_text: "<commitment 2 text>"
+      commitment_type: ...
+      required_evidence_type: ...
+      fulfillment_status: ...
+
+# concern 2 (single commitment)
+- concern_id: <R2-1>
+  commitment_extracted:
+    - commitment_text: "<commitment text>"
+      commitment_type: ...
+      required_evidence_type: ...
+      fulfillment_status: ...
+
+# concern 3 carries no commitments (positive comment) → commitment_extracted: []
+```
+
+---
+
+## Status Values
+
+### RESOLVED
+Change made; reviewer concern fully addressed.
+- **Must specify**: exact location of change (section, paragraph, page number)
+- **Must include**: brief description of what was changed
+- **Example**: "Added three additional references supporting the methodology choice (Section 3.2, paragraph 2)"
+
+### DELIBERATE_LIMITATION
+Acknowledged as a boundary condition of the study design (not a flaw).
+- **Must provide**: justification for why this is a design boundary, not an oversight
+- **Must include**: reference to the Limitations section where this is discussed
+- **Example**: "Cross-sectional design is acknowledged in Limitations (Section 5.3). Longitudinal follow-up is recommended as future research."
+
+### UNRESOLVABLE
+Would require fundamentally different research design to address.
+- **Must explain**: the specific constraint that prevents resolution
+- **Must recommend**: as a direction for future research
+- **Example**: "Addressing this would require a randomized controlled trial, which was not feasible given ethical constraints. Added to Future Research (Section 5.4)."
+
+### REVIEWER_DISAGREE
+Respectful disagreement with the reviewer's suggestion on methodological or theoretical grounds.
+- **Must provide**: evidence-based rebuttal with citations
+- **Must demonstrate**: that the reviewer's concern was carefully considered
+- **Example**: "We respectfully maintain our analytical approach. Smith (2022) and Chen (2023) both validate this method for our sample size and data structure. Response letter includes detailed justification."
+
+---
+
+## Commitment Ledger (Kong A1 / v3.11)
+
+Per Schema 11 v3.11, each row of the Revision Tracking Table may carry an extracted commitment list. Each commitment has a `fulfillment_status` chosen from:
+
+### fulfilled
+The commitment was addressed. Required evidence (per `required_evidence_type`) is present and substantively addresses the `commitment_text`. The verification site depends on the evidence type:
+- For the seven **manuscript-evidence** types (`new_section` / `new_figure` / `new_table` / `new_citation` / `methods_paragraph` / `discussion_paragraph` / `prose_edit`), the evidence lives at `revision_location` in the revised manuscript. `prose_edit` covers sentence- or paragraph-level changes (typo fixes, terminology clarifications, equation formatting, citation-style corrections) too granular for the other categories.
+- For `acknowledgment_only`, the evidence lives in the Response to Reviewers (Schema 8); the manuscript does NOT need to change. `revision_location` may be empty or point to the response letter.
+- For `other` (escape hatch for uncategorizable evidence), re-review surfaces an `EVIDENCE_TYPE_UNSPECIFIED` advisory prompting the author to specify the actual evidence location; verify at `revision_location` if populated.
+
+### partial
+Evidence exists but does not fully address the commitment. Example: reviewer asked for ablation on dataset X; revision adds ablation on dataset Y. Author must populate `unfulfilled_rationale` with the gap explanation.
+
+### not-fulfilled
+Required evidence is absent. Author must populate `unfulfilled_rationale` with one of:
+- "done elsewhere, see §X" pointer
+- "rejected, reasons: …" rationale
+- "deferred to future work" acknowledgment
+
+Silent omission triggers `COMMITMENT_GAP` advisory at re-review.
+
+### explicitly-rejected-with-rationale
+Author has decided not to address the commitment and has provided one of the three rationale forms above. This is **not** a failure — it is a documented, defensible decision. Re-review records it without raising `COMMITMENT_GAP`.
+
+**Authoring guidance:** Fill in each commitment's extraction fields first (typically via `revision_coach_agent` Step 3.5 output — `commitment_text` / `commitment_type` / `required_evidence_type`); append `fulfillment_status` (and `unfulfilled_rationale` when non-fulfilled) **on the same commitment object** as revision execution progresses. By final submission, every non-fulfilled commitment must have a rationale on its own object.
+
+**Nested-object shape (#268, supersedes the Kong A1 parallel-list cells):** Each commitment is one object in the concern's `commitment_extracted` list, carrying its own `fulfillment_status` and (when non-fulfilled) `unfulfilled_rationale`. There is no separate Fulfillment / Unfulfilled-Rationale column to align — status and rationale travel **with** the commitment they describe, so a dropped separator or numbering error cannot pair a status with the wrong commitment (the desync failure mode #268 closes). Omit `unfulfilled_rationale` entirely on a `fulfilled` commitment (no `""` placeholder). For positive comments with no extractable commitment, set `commitment_extracted: []` to mark the absence explicitly.
+
+---
+
+## Response Letter Structure
+
+When preparing the response letter to accompany the revised manuscript, use this structure:
+
+```
+Dear Editor and Reviewers,
+
+Thank you for the thoughtful and constructive feedback on our manuscript
+"[Paper Title]" (Manuscript ID: [ID]).
+
+We have carefully addressed all comments and provide point-by-point
+responses below. Changes in the manuscript are highlighted in [yellow/
+tracked changes].
+
+---
+
+## Response to Reviewer 1
+
+### Comment R1-1: [Brief summary of comment]
+**Type**: [Major/Minor/Editorial]
+**Response**: [Your response]
+**Changes made**: [Location and description of changes]
+
+### Comment R1-2: ...
+
+---
+
+## Response to Reviewer 2
+[Same format]
+
+---
+
+## Summary of Changes
+- Total comments addressed: [N]
+- Word count change: [±N words]
+- New references added: [N]
+- New figures/tables added: [N]
+
+We believe these revisions have substantially strengthened the manuscript
+and look forward to your further evaluation.
+
+Sincerely,
+[Author(s)]
+```
+
+---
+
+## Summary Statistics
+
+| Metric | Count |
+|--------|-------|
+| Total items | [N] |
+| Resolved | [N] |
+| Deliberate Limitation | [N] |
+| Unresolvable | [N] |
+| Reviewer Disagree | [N] |
+| Word count change | [±N words] |
+| New references added | [N] |
+| New figures/tables added | [N] |
+
+---
+
+## Revision Completeness Checklist
+
+Before submitting the revision, verify:
+
+- [ ] Every reviewer comment has a corresponding row in the tracking table
+- [ ] Every RESOLVED item specifies the exact location of the change
+- [ ] Every DELIBERATE_LIMITATION item is discussed in the Limitations section
+- [ ] Every UNRESOLVABLE item is mentioned in Future Research
+- [ ] Every REVIEWER_DISAGREE item has an evidence-based rebuttal
+- [ ] The response letter addresses all comments in order
+- [ ] Word count is within the journal's limit after revisions
+- [ ] All new references are added to the reference list
+- [ ] No new errors were introduced during revision (re-run citation check)
+- [ ] AI disclosure statement is updated to reflect revision assistance

package/vendor/ars/academic-paper/templates/theoretical_paper_template.md

@@ -0,0 +1,119 @@
+# Theoretical Paper Template
+
+## Usage
+This template provides the skeleton for a paper that develops, critiques, or extends a theoretical framework.
+
+---
+
+# [Paper Title in Title Case]
+
+**Author(s):** [Author Name(s)]
+**Affiliation(s):** [Department, Institution]
+**Date:** [Date]
+
+---
+
+## Abstract
+
+[Theoretical problem addressed: 1-2 sentences.]
+[Purpose of the analysis: 1 sentence.]
+[Analytical approach: 1 sentence.]
+[Key contribution (new framework/critique/extension): 2 sentences.]
+[Implications: 1 sentence.]
+
+**Keywords**: [keyword1], [keyword2], [keyword3], [keyword4], [keyword5]
+
+---
+
+## 1. Introduction
+
+### 1.1 The Theoretical Problem
+[What theoretical issue or gap motivates this paper?]
+
+### 1.2 Why This Theory Matters
+[What practical or intellectual consequences depend on getting this right?]
+
+### 1.3 Purpose and Contribution
+[What does this paper do? Develop, critique, extend, or synthesize?]
+
+---
+
+## 2. Background: The Theory in Context
+
+### 2.1 Origins and Development
+[Historical development of the theory. Key thinkers and milestones.]
+
+### 2.2 Key Concepts and Definitions
+[Define the core constructs, their relationships, and boundaries.]
+
+### 2.3 Current State of the Theory
+[How is the theory used today? Dominant interpretations and applications.]
+
+---
+
+## 3. Critical Analysis
+
+### 3.1 Strengths of the Framework
+[What does the theory do well? Evidence of its explanatory power.]
+
+### 3.2 Limitations and Gaps
+[Where does the theory fall short? What can't it explain?]
+
+### 3.3 Competing Perspectives
+[What alternative theories address the same phenomena? How do they compare?]
+
+### 3.4 Empirical Support (or Lack Thereof)
+[What does the evidence say? Are the theory's predictions supported?]
+
+---
+
+## 4. Proposed Extension / Revision
+
+### 4.1 New Dimensions or Modifications
+[What changes or additions does this paper propose?]
+
+### 4.2 Conceptual Model
+[Present the revised or new framework, ideally with a visual model.]
+
+### 4.3 Propositions for Testing
+[What testable predictions does the revised framework generate?]
+
+| Proposition | Description | Testable Via |
+|-------------|-------------|-------------|
+| P1 | [proposition] | [method] |
+| P2 | [proposition] | [method] |
+| P3 | [proposition] | [method] |
+
+---
+
+## 5. Applications and Implications
+
+### 5.1 Theoretical Implications
+[How does this contribute to the broader theoretical landscape?]
+
+### 5.2 Practical Applications
+[How can practitioners use this framework?]
+
+### 5.3 Methodological Implications
+[What new methods does this framework call for?]
+
+---
+
+## 6. Conclusion
+
+### 6.1 Summary of Contribution
+[1 paragraph restating the paper's key contribution.]
+
+### 6.2 Limitations of the Analysis
+[Acknowledge the boundaries of this theoretical work.]
+
+### 6.3 Future Directions
+[What research should follow?]
+
+---
+
+## AI Disclosure
+[Standard AI disclosure statement.]
+
+## References
+[Complete reference list.]