skills/imbad0202__academic-research-skills
1
0
Fork 0
mirror of https://github.com/Imbad0202/academic-research-skills.git synced 2026-09-14 13:51:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(prompts): retire expired writing-harness scaffolds in 4 Bucket A agents (#476 P2) (#478)

Browse Source 
Applies the 5 P2 findings from the 2026-07 harness-retirement audit plus one
adjacent duplication found while applying F-004. All reductions; no behavior
added; every domain convention and load-bearing constraint preserved.

- abstract_bilingual (F-001): dedupe the "Common Errors" list against the
  Independence red flags above; keep only the non-overlapping per-language points.
- citation_compliance (F-002): collapse the 3-step format auto-detect ladder to a
  signature table + the one-line "default APA 7th" fallback (fallback preserved).
- research_question (F-003): rewrite the Socratic "What It Does NOT Do" negatives
  as positives; preserve the failure_paths F1 escape-hatch (its only definition).
- draft_writer (F-004): collapse the triple-templated drafting block (step-by-step
  algorithm + duplicate TEEL framework + duplicate register table) to the TEEL
  convention + drafting order; TEEL now single-sourced at Paragraph Structure.
- draft_writer (F-005): 4 basic citation-format examples -> one rule + the
  page-locator direct-quote example.
- draft_writer (adjacent, user-approved): citation-method decision tree deduped to
  the two non-redundant cases (contrastive + secondary citation).

Net -112 lines. Full CI pytest manifest green. Report-scope only; no contract,
no lint-mirrored prose, no Phase Boundary / citation-contract / formatter-gate touched.

Refs #476.


Claude-Session: https://claude.ai/code/session_01N9rzRUcxhpjJsY5zTEPtKQ

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Edward Cheng-I Wu
2026-07-01 18:00:51 +08:00
committed by GitHub
parent bbad72e89c
commit 96e4f98b6e
4 changed files with 35 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
academic-paper/agents/abstract_bilingual_agent.md
+3 -10
View File
@@ -121,17 +121,10 @@ Green flags for independent writing:
## Common Errors to Avoid
### English Abstract
- Starting with "This paper..." (vary openings)
- Vague findings ("results were significant")
- Including methodology details that don't matter for the abstract
- Using abbreviations without definition (in abstract, always define)
Distinct from the Independence Verification red flags above (which check English↔Chinese independence); these are per-language writing-quality points:
### Chinese Abstract
- Translation tone (directly translating English grammar)
- Overuse of passive voice (Chinese prefers active voice)
- Overly long subordinate clauses (Chinese prefers short sentences)
- Inconsistent academic terminology (using different translations for the same concept)
- **English**: vary openings (not every abstract starts "This paper..."); state concrete findings, not "results were significant"; drop methodology detail that doesn't earn its place in an abstract; define every abbreviation on first use.
- **Chinese**: prefer active voice over passive (Chinese reads more naturally active); prefer short sentences over long subordinate clauses; keep academic terminology consistent (one translation per concept). (Translation tone is already covered by the Independence red flags above.)
## Output Format
academic-paper/agents/citation_compliance_agent.md
+9 -17
View File
@@ -242,25 +242,17 @@ Step 6: Output
### Citation Format Auto-Detection
```
When receiving a paper without an explicitly specified citation format:
When no citation format is specified, identify it from the in-text form, confirming against the reference-list layout:
Step 1: Sample Check (extract first 5 in-text citations)
├── See (Author, Year) -> possibly APA or Chicago Author-Date
├── See [N] numbered -> possibly IEEE or Vancouver
├── See (Author Page) without year -> possibly MLA
├── See footnote/endnote -> possibly Chicago Notes-Bibliography
└── See superscript number -> possibly Vancouver
| In-text signature | Reference-list confirmation | Format |
|---|---|---|
| `(Author, Year)` | hanging indent, DOI as URL, sentence-case titles | APA |
| `(Author, Year)` or footnotes | Author-Date + Reference List, or footnotes + Bibliography | Chicago |
| `(Author Page)`, no year | Works Cited, containers model | MLA |
| numbered `[N]` | numbered list, conference proceedings common | IEEE |
| superscript number | numbered, superscript, medical journals common | Vancouver |
Step 2: Confirm (check Reference List format)
├── APA: hanging indent, DOI as URL, sentence case titles
├── Chicago: footnotes + Bibliography, or Author-Date + Reference List
├── MLA: Works Cited, containers model, no DOI in old MLA
├── IEEE: numbered [1], conference proceedings common
└── Vancouver: numbered, superscript, medical journals common
Step 3: If unable to determine -> ask user; if user does not respond -> default to APA 7th
```
If the format cannot be determined, ask the user; if the user does not respond, default to **APA 7th**.
### Core Verification Rules by Format
academic-paper/agents/draft_writer_agent.md
+19 -110
View File
@@ -96,26 +96,19 @@ Reference: `references/academic_writing_style.md`
| Engineering | Problem-solution oriented, specification-precise |
| Education | Practice-oriented, stakeholder-aware, impact-focused |
| Medicine | Evidence hierarchy-conscious, clinical precision |
| Business/Management | Problem-solution oriented, ROI/strategic-implication framing, practical recommendations |
### Paragraph Structure
Each paragraph should follow:
1. **Topic sentence** — states the paragraph's main point
2. **Evidence/support** — 2-3 sentences with citations
3. **Analysis/interpretation** — connects evidence to the argument
4. **Transition** — links to the next paragraph
### Paragraph Structure (TEEL)
Each paragraph follows the TEEL shape:
1. **T — Topic sentence** — states the paragraph's main point
2. **E — Evidence** — 2-3 sentences with citations
3. **E — Explanation** — connects evidence to the argument (analysis, not just data)
4. **L — Link** — transitions to the next paragraph
### Citation Integration
**Narrative (author as subject)**:
> Smith (2024) demonstrated that AI-assisted QA reduces evaluation variance by 23%.
Use narrative citations (author as sentence subject) and parenthetical citations as the argument requires; group multiple sources in one parenthetical where they support the same point. Use direct quotes sparingly, and always with a page locator:
**Parenthetical (author in parentheses)**:
> AI-assisted QA has been shown to reduce evaluation variance significantly (Smith, 2024).
**Multiple sources**:
> Several studies have confirmed this finding (Chen, 2023; Kim, 2024; Smith, 2024).
**Direct quote (use sparingly)**:
> As Smith (2024) noted, "the reduction in variance was statistically significant across all institutional types" (p. 45).
## Word Count Tracking
@@ -183,89 +176,17 @@ When receiving feedback from peer_reviewer_agent (Phase 6 -> back to Phase 4):
| ... | ... | ... | ... |
```
## Detailed Execution Algorithm
## Paragraph Structure Convention (TEEL)
### Section-by-Section Writing Strategy
Body paragraphs follow the TEEL shape already defined under *Paragraph Structure* above (topic → evidence-with-citation → analysis → link). Conventions that constrain it:
```
INPUT: Paper Outline + Argument Blueprint + Annotated Bibliography
OUTPUT: Complete Draft (produced section by section)
- **Length**: 120-200 words (EN) / 200-350 characters (zh-TW); at least 3 body paragraphs per section.
- **Exception**: the opening paragraph of the Introduction and the closing paragraph of the Conclusion need not follow TEEL.
- **Evidence discipline**: prefer paraphrase; limit direct quotes to one per section.
Phase A: Preparation (before each section begins)
1. Read the section's Outline (Purpose + Content Summary + Key Sources + Key Arguments)
2. Read the section's CER chains (from Argument Blueprint)
3. Prepare the section's citation list (from Annotated Bibliography -> Potential Use)
4. Confirm word count target (from Word Count Allocation)
Recommended drafting order (not mandatory): Introduction first (sets tone), then Literature Review → Methodology → Results → Discussion → Conclusion, and the Abstract last (it summarizes the finished paper). Write the Abstract elsewhere only if the user asks for a specific section first.
Phase B: Writing (strictly section by section)
Writing order decision:
├── Recommended order (not mandatory):
│ 1. Introduction (write first, establish tone)
│ 2. Literature Review (lay out background)
│ 3. Methodology (explain methods)
│ 4. Results / Analysis (present findings)
│ 5. Discussion (discuss significance)
│ 6. Conclusion (summarize)
│ 7. Abstract (write last, since it needs to summarize the whole paper)
└── Exception: user requests writing a specific section first -> follow user
Writing flow for each section:
1. Write Opening paragraph (introduction + section preview)
2. Write Body paragraphs following CER chain
3. Each paragraph follows TEEL structure (see below)
4. Write Closing paragraph (summary + transition to next section)
5. Calculate word count -> compare against target
6. IF deviation > +/-15% -> adjust immediately (trim or expand)
Phase C: Assembly
1. Combine all sections
2. Check inter-section transitions for smoothness
3. Add Title page + Reference list placeholder
4. Calculate total word count and produce Draft Metadata
```
### Paragraph Structure Rules (TEEL Framework)
Each Body paragraph must contain 4 components:
```
T — Topic Sentence
-> States the core point of the paragraph
-> Length: 1 sentence
-> Directly related to section Purpose
E — Evidence
-> Cite literature to support the topic sentence
-> Length: 2-3 sentences
-> Use narrative or parenthetical citation
-> Prefer paraphrasing; direct quotes limited to 1 per section
E — Explanation
-> Analyze how the evidence supports the topic sentence
-> Length: 1-2 sentences
-> This is where the author demonstrates analytical ability
-> Must not merely list data without explanation
L — Link
-> Connect to the next paragraph or tie back to section argument
-> Length: 1 sentence
-> Use transition words/phrases
```
**Paragraph length standard**: Each paragraph 120-200 words (EN) or 200-350 characters (zh-TW)
**Minimum per section**: At least 3 TEEL paragraphs
**Exceptions**: The first paragraph of Introduction and the last paragraph of Conclusion need not strictly follow TEEL
### Academic Writing Register Adjustment
| Discipline | Register Characteristics | Preferred Structural Phrases | Avoid |
|------|---------|-----------|------|
| Social Sciences | Theory-oriented, reflexive | "This study argues...", "The findings suggest..." | Over-simplifying causal relationships |
| Science/Engineering | Precise, measurement-oriented | "The results indicate...", "The system achieves..." | Subjective evaluative terms |
| Humanities | Interpretive, argument-driven | "It can be argued that...", "This reading reveals..." | Quantitative reductionism of complex phenomena |
| Education | Practice-oriented, stakeholder-aware | "Practitioners may...", "The implications for..." | Ignoring field context |
| Medicine | Evidence hierarchy-conscious, clinically precise | "Level I evidence shows...", "Clinical significance..." | Confusing statistical significance with clinical significance |
| Business/Management | Problem-solution oriented | "The ROI analysis indicates...", "Strategic implications..." | Purely academic discourse without practical recommendations |
Register cues by discipline are in *Discipline-Specific Adjustments* above; do not restate them here.
**Additional rules for Chinese academic register**:
- Use "this study" rather than "we"
@@ -274,22 +195,10 @@ L — Link
### Citation Integration Strategy
```
Decision tree for choosing citation method:
├── Is there a single clear source for this point?
│ ├── Want to emphasize author's contribution -> Narrative citation: Smith (2024) demonstrated...
│ └── Author not important, point is important -> Parenthetical citation: ...(Smith, 2024).
├── Are multiple sources supporting this point?
│ └── Synthesized citation: Several studies have confirmed... (A, 2023; B, 2024; C, 2024).
├── Need to quote the original text?
│ └── Direct quote (<=1 per section): As Smith (2024) noted, "exact words" (p. 45).
│ -> Only when: (a) precise wording matters, (b) definitional statement, (c) particularly powerful expression
├── Is the cited viewpoint different from this paper's position?
│ └── Contrastive citation: While Smith (2024) argued X, this study contends Y because...
└── Secondary citation (have not personally read the original)?
└── Secondary citation: (Original, Year, as cited in Citing, Year)
-> Limit: <=3 secondary citations per paper
```
Choose narrative / parenthetical / direct-quote forms per *Citation Integration* above. Two further cases:
- **Contrastive** (cited view differs from this paper's position): `While Smith (2024) argued X, this study contends Y because…`
- **Secondary** (you have not read the original): `(Original, Year, as cited in Citing, Year)` — limit ≤3 secondary citations per paper.
### Transition Words and Phrases Guide
deep-research/agents/research_question_agent.md
+4 -9
View File
@@ -125,16 +125,11 @@ ASSUMPTIONS:
When mode = `socratic`, this agent's behavior changes as follows.
### What It Does NOT Do
In Socratic mode the deliverable shifts from producing the RQ to helping the user derive it:
- **Does not directly produce an RQ Brief**: The RQ Brief is a full mode output; the goal of Socratic mode is to guide the user to derive it themselves
- **Does not score FINER on behalf of the user**: Does not automatically produce a FINER score table
- **Does not proactively generate candidate RQs**: Unless the user cannot converge after 5+ rounds in Layer 1 (see failure_paths F1)
### What It Does Instead
- **Guides the user to derive the RQ themselves**: Uses guiding questions from the FINER framework to help the user discover the contours of their research question
- **Uses FINER as a guidance tool (not a scoring tool)**: Designs 2-3 guiding questions for each FINER dimension
- **Guide the user to derive the RQ themselves** — the RQ Brief is a full-mode output; here you use guiding questions to help the user discover the contours of their own question.
- **Use FINER as a guidance tool, not a scoring tool** — design 2-3 guiding questions per FINER dimension rather than producing a score table.
- **Withhold candidate RQs** until the user cannot converge after 5+ rounds in Layer 1 (the `failure_paths F1` escape hatch); only then offer candidates.
#### FINER Guiding Questions