psyclaw 0.27.23 → 0.28.1

package/vendor/ars/academic-paper/references/writing_quality_check.md

@@ -0,0 +1,173 @@
+# Writing Quality Check
+
+## Purpose
+
+A set of writing quality rules extracted from common patterns in AI-generated text. These are **good writing rules** that apply regardless of whether the text was AI-generated or human-written. The goal is better prose, not detection evasion.
+
+> **Design boundary**: This checklist improves writing quality. It is NOT a humanizer. We do not aim to fool AI detectors. We aim to produce clear, precise, varied academic prose.
+
+Reference this checklist during the self-review step of drafting (draft_writer_agent Step 2.7, report_compiler_agent final check).
+
+---
+
+## A. High-Frequency Term Warnings
+
+The following terms appear disproportionately in AI-generated text. They are not banned — but when you encounter one, ask: **"Is this really the most precise word here, or am I defaulting to it?"**
+
+### Flagged Terms
+
+| Term | Why it's flagged | Better alternatives (context-dependent) |
+|------|-----------------|----------------------------------------|
+| delve | Overused as "explore" substitute | examine, investigate, analyze, explore |
+| tapestry | Cliché metaphor for complexity | network, interplay, system, landscape |
+| landscape | Vague when not literal | field, domain, context, state of |
+| pivotal | Inflation of importance | important, significant, central, key |
+| crucial | Same as above | essential, necessary, critical, vital |
+| foster | Vague verb | promote, develop, cultivate, encourage |
+| showcase | Non-academic register | demonstrate, illustrate, present, reveal |
+| testament | Cliché | evidence, indicator, demonstration |
+| navigate | Vague when not literal | manage, address, handle, negotiate |
+| leverage | Business jargon | use, employ, utilize, apply |
+| realm | Archaic/poetic | domain, field, area, sphere |
+| embark | Overwrought for "begin" | begin, initiate, undertake, start |
+| underscore | Overused emphasis verb | emphasize, highlight, stress, reinforce |
+| multifaceted | Vague complexity claim | complex, varied, diverse, multilayered |
+| nuanced | Often vacuous | subtle, detailed, fine-grained, qualified |
+| comprehensive | Often unjustified | thorough, extensive, broad, detailed |
+| robust | Vague quality claim | reliable, strong, rigorous, resilient |
+| intricate | Same problem as multifaceted | complex, detailed, elaborate, involved |
+| cornerstone | Cliché metaphor | foundation, basis, core element, pillar |
+| paradigm | Overused outside philosophy of science | framework, model, approach (exception: "paradigm shift" in philosophy of science is standard) |
+| synergy | Business jargon | interaction, cooperation, combined effect |
+| holistic | Vague without definition | comprehensive, integrated, whole-system |
+| streamline | Non-academic | simplify, optimize, improve efficiency |
+| cutting-edge | Cliché | recent, advanced, state-of-the-art, novel |
+| groundbreaking | Inflation | novel, innovative, pioneering, original |
+
+### Exception Rule
+
+If a flagged term is **standard terminology in the target discipline**, it is exempt:
+- "paradigm shift" in philosophy of science → OK
+- "landscape" in ecology/geography (literal) → OK
+- "robust" in statistics ("robust estimator") → OK
+- "navigate" in wayfinding research (literal) → OK
+
+---
+
+## B. Punctuation Pattern Control
+
+### Em Dash (—)
+- **Limit**: ≤ 3 per paper total, recommend 0-1
+- **Why**: AI text overuses em dashes for parenthetical asides. Academic writing typically uses commas, parentheses, or separate sentences instead
+- **Fix**: Replace with commas, parentheses, or restructure into separate sentences
+- **Exception**: Direct quotes from sources retain their original punctuation
+
+### Semicolons
+- **Limit**: ≤ 2 per 1000 words
+- **Why**: AI text chains independent clauses with semicolons where a period would be clearer
+- **Fix**: Use a period and start a new sentence. Reserve semicolons for closely related parallel structures
+
+### Colon-List Sequences
+- **Rule**: Avoid 2+ consecutive paragraphs that each open with a colon followed by a list
+- **Why**: Creates a monotonous enumerate-everything pattern
+- **Fix**: Integrate list items into prose, or use a single consolidated list
+
+---
+
+## C. Throat-Clearing Openers
+
+Delete the following sentence starters. Cut to the point.
+
+| Throat-clearing phrase | What to do |
+|-----------------------|-----------|
+| "In the realm of..." | Delete. Start with the actual subject |
+| "It's important to note that..." | Delete. If it's important, the content speaks for itself |
+| "It is worth mentioning that..." | Same as above |
+| "In today's rapidly evolving..." | Delete. Timestamped clichés add no information |
+| "This serves as a testament to..." | Replace with direct claim: "This demonstrates..." or just state the evidence |
+| "It goes without saying that..." | If it goes without saying, don't say it |
+| "In order to..." | Replace with "To..." |
+| "It should be noted that..." | Delete. Just note it |
+| "As a matter of fact..." | Delete. State the fact |
+| "When it comes to..." | Replace with the subject directly: "X shows..." |
+| "At the end of the day..." | Delete. Colloquial and vague |
+| "With that being said..." | Delete or use "However" if a contrast is intended |
+
+### Meta-Commentary to Avoid
+
+Also watch for sentences that describe what the paper is doing instead of doing it:
+- "This section will discuss..." → Just discuss it
+- "The following paragraph examines..." → Just examine it
+- "We now turn our attention to..." → Just turn to it
+
+Exception: Roadmap sentences in the Introduction ("Section 2 reviews the literature; Section 3 describes the methodology") are standard academic practice and should be kept.
+
+---
+
+## D. Structure Pattern Warnings
+
+### Rule of Three Compulsion
+- **Pattern**: Every argument has exactly 3 sub-points, every list has exactly 3 items
+- **Why**: Real analysis doesn't always decompose into trios. Two strong points beat three padded ones
+- **Fix**: Use as many points as the evidence warrants. 2 is fine. 5 is fine. Don't pad to 3
+
+### Uniform Paragraph Length
+- **Pattern**: All paragraphs are approximately the same length (150-200 words each)
+- **Why**: Natural writing has paragraph length variation. Short paragraphs for emphasis, longer ones for complex arguments
+- **Fix**: Vary paragraph length. A 2-sentence paragraph after a 10-sentence paragraph creates rhythm
+
+### Synonym Cycling
+- **Pattern**: Using 3+ different synonyms for the same concept within one paragraph to avoid repetition
+- **Why**: In academic writing, consistent terminology is a virtue. Swapping "students" → "learners" → "participants" → "subjects" within one paragraph confuses rather than impresses
+- **Fix**: Pick one term per concept per section. Repeat it. Technical repetition is clarity, not weakness
+
+### Binary Contrast Overuse
+- **Pattern**: "Not X. Y." or "It's not about X — it's about Y." used more than twice per paper
+- **Why**: This rhetorical device is effective once. Repeated, it becomes a tic
+- **Limit**: ≤ 2 per paper
+
+### Mirror Structure
+- **Pattern**: Every section has the same internal structure (topic sentence → 3 evidence points → synthesis sentence)
+- **Why**: Creates a template-stamped feel. Different sections serve different purposes and should have different internal rhythms
+- **Fix**: Let section structure follow content needs. Methods can be procedural. Discussion can be exploratory
+
+---
+
+## E. Burstiness (Sentence Length Variation)
+
+### What to Check
+Good writing has **natural variation in sentence length**. Short sentences create impact. Longer sentences develop complex ideas. The alternation creates rhythm.
+
+### Detection Rule
+If 5+ consecutive sentences all fall within a narrow word-count range (e.g., all between 20-25 words): **flag for review**.
+
+### How to Fix
+- Insert a short sentence (≤ 10 words) to break the pattern
+- Combine two short sentences into one complex one if the pattern is monotonously short
+- Read the paragraph aloud — if it feels metronomic, vary it
+
+### Burstiness Targets (by section)
+- **Abstract**: Moderate variation (factual, steady pace)
+- **Introduction**: High variation (hook with short sentences, build with long ones)
+- **Literature Review**: Moderate (steady analytical pace, occasional short synthesis)
+- **Methods**: Low variation acceptable (procedural sections naturally have uniform length)
+- **Results**: Moderate (short for key findings, longer for detailed descriptions)
+- **Discussion**: Highest variation (short for emphasis, long for interpretation, very short for conclusions)
+
+---
+
+## How to Use This Checklist
+
+### During Drafting (Preferred)
+Apply rules **while writing each section** in the self-review sub-step (Step 2.7 in draft_writer_agent). This catches issues before they propagate.
+
+### During Final Review (Fallback)
+If not applied during drafting, run a full-paper sweep before handoff to citation_compliance_agent.
+
+### Scoring (Internal, Not Reported to User)
+For each rule category, track violations:
+- 0 violations: Clean
+- 1-3 violations: Minor — fix in self-review
+- 4+ violations: Pattern issue — review the section's writing approach
+
+Do NOT report scores to the user. Just fix the issues silently during drafting.

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

@@ -0,0 +1,78 @@
+# Bilingual Abstract Template
+
+## Usage
+Use this template when writing bilingual abstracts (English + Traditional Chinese). Each version must be independently composed — not a translation of the other.
+
+---
+
+## English Abstract
+
+### [Paper Title in Title Case]
+
+[**Background** — 1-2 sentences: Establish the context and identify the research problem.]
+
+[**Purpose** — 1 sentence: State the specific research objective or question.]
+
+[**Method** — 1-2 sentences: Describe the research approach, data sources, and analytical method.]
+
+[**Findings** — 2-3 sentences: Present the key results. Include specific details, numbers, or effect sizes where applicable.]
+
+[**Implications** — 1-2 sentences: State the significance, practical impact, or contribution to the field.]
+
+**Keywords**: [keyword 1], [keyword 2], [keyword 3], [keyword 4], [keyword 5], [keyword 6] *(optional)*, [keyword 7] *(optional)*
+
+*Target: 150-300 words*
+
+---
+
+## Chinese Abstract (zh-TW)
+
+### [Paper Title in Chinese]
+
+[**Research Background** — 1-2 sentences: Describe the research context and the problem being investigated.]
+
+[**Research Purpose** — 1 sentence: Clearly state the research objective or research question.]
+
+[**Research Method** — 1-2 sentences: Describe the research methodology, data sources, and analytical strategy.]
+
+[**Research Findings** — 2-3 sentences: Present the main research results, including specific data or key findings.]
+
+[**Research Significance** — 1-2 sentences: Explain the research contribution, practical implications, or theoretical value.]
+
+**Keywords**: [Keyword 1], [Keyword 2], [Keyword 3], [Keyword 4], [Keyword 5], [Keyword 6] (optional), [Keyword 7] (optional)
+
+*Target word count: 300-500 Chinese characters*
+
+---
+
+## Quality Checklist
+
+| Check | EN | zh-TW |
+|-------|:--:|:-----:|
+| Covers all 5 components (Background, Purpose, Method, Findings, Implications) | ☐ | ☐ |
+| Within word count range | ☐ | ☐ |
+| Independently composed (not a translation) | ☐ | ☐ |
+| Key findings match between versions | ☐ | ☐ |
+| Quantitative data consistent | ☐ | ☐ |
+| 5-7 keywords provided | ☐ | ☐ |
+| Keywords complement title (not duplicate) | ☐ | ☐ |
+| No citations in the abstract | ☐ | ☐ |
+| No undefined abbreviations | ☐ | ☐ |
+| Reads naturally in target language | ☐ | ☐ |
+
+---
+
+## Guidelines
+
+### Independence Test
+Your abstracts are truly independent if:
+- Sentence structures differ between languages
+- The Chinese version uses natural Chinese academic phrasing (not translationese)
+- Minor details may be grouped or reordered to suit each language's conventions
+- Both versions stand alone as complete summaries
+
+### Keywords Strategy
+- English and Chinese keywords should cover similar conceptual space
+- Keywords should complement (not duplicate) the title
+- Mix broad discipline terms with specific research terms
+- Include methodology terms if distinctive

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

@@ -0,0 +1,129 @@
+# Case Study Paper Template
+
+## Usage
+This template provides the skeleton for an in-depth case study paper analyzing specific institutions, programs, events, or phenomena.
+
+---
+
+# [Paper Title in Title Case]
+
+**Author(s):** [Author Name(s)]
+**Affiliation(s):** [Department, Institution]
+**Date:** [Date]
+
+---
+
+## Abstract
+
+[Background and case significance: 1-2 sentences.]
+[Purpose: 1 sentence.]
+[Method and data sources: 1-2 sentences.]
+[Key findings from the case: 2-3 sentences.]
+[Lessons and transferability: 1 sentence.]
+
+**Keywords**: [keyword1], [keyword2], [keyword3], [keyword4], [keyword5]
+
+---
+
+## 1. Introduction
+
+### 1.1 Background and Rationale
+[Why study this case? What makes it significant or instructive?]
+
+### 1.2 Case Selection Justification
+[Why this specific case? Intrinsic interest, typicality, or extreme/deviant case?]
+
+### 1.3 Research Questions
+1. **RQ1**: [Question 1]?
+2. **RQ2**: [Question 2]?
+
+---
+
+## 2. Literature Context
+
+### 2.1 Relevant Theoretical Framework
+[What theory informs the analysis?]
+
+### 2.2 Prior Research on Similar Cases
+[What do we know from comparable cases?]
+
+---
+
+## 3. Case Description
+
+### 3.1 Context and Setting
+[Institutional/organizational/geographical context.]
+
+### 3.2 Key Actors and Stakeholders
+[Who are the main players? What are their roles and interests?]
+
+### 3.3 Timeline of Events
+[Chronological narrative of key developments.]
+
+| Period | Key Event | Significance |
+|--------|-----------|-------------|
+| [Date] | [Event] | [Why it matters] |
+
+### 3.4 Data Sources
+[Documents, interviews, observations, archival data used.]
+
+---
+
+## 4. Analysis
+
+### 4.1 Analysis Framework
+[How the data were analyzed. Coding strategy, analytical lens.]
+
+### 4.2 [Theme/Finding 1]
+[Detailed analysis with evidence from the case data.]
+
+### 4.3 [Theme/Finding 2]
+[Detailed analysis with evidence from the case data.]
+
+### 4.4 [Theme/Finding 3]
+[Detailed analysis with evidence from the case data.]
+
+---
+
+## 5. Discussion
+
+### 5.1 Cross-Theme Synthesis
+[How do the themes/findings relate to each other?]
+
+### 5.2 Comparison with Literature
+[How does this case compare with prior research?]
+
+### 5.3 Theoretical Insights
+[What does this case contribute to theory?]
+
+### 5.4 Transferability
+[To what extent can lessons from this case apply elsewhere? (Note: case studies aim for transferability, not generalizability.)]
+
+---
+
+## 6. Lessons Learned and Recommendations
+
+### 6.1 For Practitioners
+[Actionable recommendations for people in similar situations.]
+
+### 6.2 For Policymakers
+[Policy implications from the case.]
+
+### 6.3 For Researchers
+[What further research does this case suggest?]
+
+---
+
+## 7. Conclusion
+[Key takeaways and closing statement.]
+
+---
+
+## AI Disclosure
+[Standard AI disclosure statement.]
+
+## References
+[Complete reference list.]
+
+## Appendices
+### Appendix A: [Case Documents / Interview Protocol / Data Summary]

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

@@ -0,0 +1,108 @@
+# Conference Paper Template
+
+## Usage
+This template provides the skeleton for a concise conference paper presenting research findings. Adapt length and depth to the specific conference requirements (typically 2,000-5,000 words).
+
+---
+
+# [Paper Title in Title Case]
+
+**Author(s):** [Author Name(s)]¹, [Co-Author]²
+**¹** [Department, Institution, City, Country]
+**²** [Department, Institution, City, Country]
+**Contact:** [email@example.com]
+
+---
+
+## Abstract
+
+[Problem and motivation: 1 sentence.]
+[Approach: 1 sentence.]
+[Key results: 1-2 sentences.]
+[Significance: 1 sentence.]
+
+**Keywords**: [keyword1], [keyword2], [keyword3], [keyword4], [keyword5]
+
+---
+
+## 1. Introduction
+
+### 1.1 Problem and Motivation
+[What problem does this research address? Why is it important?]
+[1-2 paragraphs]
+
+### 1.2 Research Question(s)
+[State the specific question(s) this paper addresses.]
+
+### 1.3 Contribution
+[What is new? How does this paper advance the field?]
+[1 paragraph — be specific about the contribution]
+
+---
+
+## 2. Related Work
+
+### 2.1 [Key Prior Studies / Approach 1]
+[Brief review of relevant work. Focus on most relevant studies.]
+[1-2 paragraphs]
+
+### 2.2 [Key Prior Studies / Approach 2]
+[1-2 paragraphs]
+
+### 2.3 Gap This Paper Addresses
+[1 paragraph — how does this paper differ from or extend prior work?]
+
+---
+
+## 3. Approach / Methodology
+
+### 3.1 Research Design
+[What method was used and why?]
+
+### 3.2 Data / Materials
+[What data were collected or used? Sample/dataset description.]
+
+### 3.3 Analysis
+[How were the data analyzed?]
+
+---
+
+## 4. Results
+
+### 4.1 [Key Finding 1]
+[Present results with supporting evidence (tables, figures).]
+
+### 4.2 [Key Finding 2]
+[Present results with supporting evidence.]
+
+### 4.3 [Key Finding 3] *(if applicable)*
+[Additional findings.]
+
+---
+
+## 5. Discussion
+
+### 5.1 Interpretation
+[What do the results mean? How do they relate to existing knowledge?]
+
+### 5.2 Limitations
+[Acknowledge study limitations briefly.]
+
+---
+
+## 6. Conclusion and Future Work
+
+[Summary of contribution: 1-2 sentences.]
+[Practical implications: 1 sentence.]
+[Future work: 1-2 sentences describing next steps.]
+
+---
+
+## AI Disclosure
+[Standard AI disclosure statement.]
+
+## Acknowledgments
+[Funding sources, collaborators, reviewers.]
+
+## References
+[Complete reference list. Conference papers typically have 15-25 references.]

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

@@ -0,0 +1,132 @@
+# CRediT Statement Template
+
+## Usage
+
+Use this template to record author contributions using the CRediT (Contributor Roles Taxonomy) framework. Fill in the contribution matrix, then use the output format to generate the CRediT statement for your manuscript.
+
+Reference: `references/credit_authorship_guide.md`
+
+---
+
+## Step 1: Author Information
+
+| # | Author Name | Affiliation | ORCID | Corresponding Author? |
+|---|-------------|-------------|-------|:---------------------:|
+| 1 | [Name] | [Institution] | [0000-0000-0000-0000] | [Yes/No] |
+| 2 | [Name] | [Institution] | [0000-0000-0000-0000] | [Yes/No] |
+| 3 | [Name] | [Institution] | [0000-0000-0000-0000] | [Yes/No] |
+| 4 | [Name] | [Institution] | [0000-0000-0000-0000] | [Yes/No] |
+
+*Add rows as needed.*
+
+---
+
+## Step 2: Contribution Matrix
+
+Fill each cell with: **Lead** / **Supporting** / **--** (not involved)
+
+| CRediT Role | Author 1 | Author 2 | Author 3 | Author 4 |
+|-------------|:--------:|:--------:|:--------:|:--------:|
+| 1. Conceptualization | [ ] | [ ] | [ ] | [ ] |
+| 2. Data curation | [ ] | [ ] | [ ] | [ ] |
+| 3. Formal analysis | [ ] | [ ] | [ ] | [ ] |
+| 4. Funding acquisition | [ ] | [ ] | [ ] | [ ] |
+| 5. Investigation | [ ] | [ ] | [ ] | [ ] |
+| 6. Methodology | [ ] | [ ] | [ ] | [ ] |
+| 7. Project administration | [ ] | [ ] | [ ] | [ ] |
+| 8. Resources | [ ] | [ ] | [ ] | [ ] |
+| 9. Software | [ ] | [ ] | [ ] | [ ] |
+| 10. Supervision | [ ] | [ ] | [ ] | [ ] |
+| 11. Validation | [ ] | [ ] | [ ] | [ ] |
+| 12. Visualization | [ ] | [ ] | [ ] | [ ] |
+| 13. Writing -- original draft | [ ] | [ ] | [ ] | [ ] |
+| 14. Writing -- review & editing | [ ] | [ ] | [ ] | [ ] |
+
+---
+
+## Step 3: Output — English CRediT Statement
+
+Based on the matrix above, generate the statement in this format:
+
+```
+Author Contributions:
+[Author 1 Name]: [Role 1], [Role 2], [Role 3].
+[Author 2 Name]: [Role 1], [Role 2].
+[Author 3 Name]: [Role 1], [Role 2], [Role 3].
+```
+
+### Example (English)
+
+```
+Author Contributions:
+Yu-Chen Wang: Conceptualization, Methodology, Funding acquisition,
+Writing – original draft, Supervision, Project administration.
+Mei-Ling Chen: Data curation, Formal analysis, Software, Visualization,
+Writing – original draft, Writing – review & editing.
+Wei-Ting Lin: Investigation, Validation, Writing – review & editing.
+```
+
+---
+
+## Step 4: Output — Chinese CRediT Statement
+
+```
+Author Contribution Statement:
+[Author 1 Name]: [Role 1], [Role 2], [Role 3].
+[Author 2 Name]: [Role 1], [Role 2].
+[Author 3 Name]: [Role 1], [Role 2], [Role 3].
+```
+
+### Example (Chinese)
+
+```
+Author Contribution Statement:
+Yu-Chen Wang: Conceptualization, Methodology, Funding acquisition,
+Writing -- original draft, Supervision, Project administration.
+Mei-Ling Chen: Data curation, Formal analysis, Software, Visualization,
+Writing -- original draft, Writing -- review & editing.
+Wei-Ting Lin: Investigation, Validation, Writing -- review & editing.
+```
+
+---
+
+## Step 5: Equal Contribution Statement (Optional)
+
+If applicable, add one of the following:
+
+**English**:
+```
+[Author 1 Name] and [Author 2 Name] contributed equally to this work and
+share first authorship.
+```
+
+**Chinese**:
+```
+[Author 1 Name] and [Author 2 Name] contributed equally to this work and
+share first authorship.
+```
+
+---
+
+## Quality Checklist
+
+| Check | Status |
+|-------|:------:|
+| Every author has at least one CRediT role assigned | ☐ |
+| Every CRediT role has at least one author (if applicable to the study) | ☐ |
+| At least one author marked as "Lead" for Writing -- original draft | ☐ |
+| At least one author marked for Writing -- review & editing | ☐ |
+| Corresponding author identified | ☐ |
+| All authors meet ICMJE criteria (see `references/credit_authorship_guide.md`) | ☐ |
+| AI tools are NOT listed as authors | ☐ |
+| Equal contribution properly noted (if applicable) | ☐ |
+| CRediT statement language matches manuscript language | ☐ |
+
+---
+
+## Notes
+
+- CRediT roles should be discussed and agreed upon by **all co-authors** before submission
+- The contribution matrix serves as an internal record; the text statement is what appears in the manuscript
+- Some journals use their own submission system to collect CRediT data — in that case, use this template for preparation and enter the data into the journal's system during submission
+- For single-author papers, a CRediT statement is typically not required, but the sole author is understood to have performed all roles