Skip to content

Jobo16/ielts-buddy / skills/ielts-writing-review

ielts-writing-review

Verified

批改雅思 Task 1 或 Task 2 作文,进行写前规划、原文证据批注和二改对照;需要可下载 Word 时生成并验证文档。用户提供作文即可使用,网站连接可选。

FileKindSize
SKILL.mdskill md2.1 KB
agents/openai.yamlconfig263 B
licenses/ielts-writing-review-skills.txtmarkdown1.0 KB
licenses/third-party-skill-sources.txtmarkdown1.2 KB
manifest.jsonconfig214 B
references/api-access.mdmarkdown1.1 KB
references/browser-routes.mdmarkdown587 B
references/ielts-task1-review/WORKFLOW.mdmarkdown12.0 KB
references/ielts-task1-review/references/review_format.mdmarkdown4.4 KB
references/ielts-task1-review/references/review_plan_example.jsonconfig3.6 KB
references/ielts-task1-review/references/scoring_guide.mdmarkdown1.9 KB
references/ielts-task1-review/references/teacher_style.mdmarkdown2.8 KB
references/ielts-task1-review/references/visual_analysis_protocol.mdmarkdown3.0 KB
references/ielts-task2-review/WORKFLOW.mdmarkdown10.8 KB
references/ielts-task2-review/references/review_format.mdmarkdown5.3 KB
references/ielts-task2-review/references/review_plan_example.jsonconfig4.0 KB
references/ielts-task2-review/references/scoring_guide.mdmarkdown2.0 KB
references/ielts-task2-review/references/teacher_style.mdmarkdown3.3 KB
references/skill-taxonomy.jsonconfig1.5 KB
references/writing-revision-loop/WORKFLOW.mdmarkdown5.7 KB
references/writing-task-planning/WORKFLOW.mdmarkdown3.2 KB
references/writing-vocabulary-handoff.mdmarkdown1.4 KB
scripts/ielts-task1-review/create_and_validate_task1_review.pyscript2.4 KB
scripts/ielts-task1-review/create_task1_review_docx.pyscript34.7 KB
scripts/ielts-task1-review/extract_docx_images.pyscript1.5 KB
scripts/ielts-task1-review/extract_task1_input.pyscript6.1 KB
scripts/ielts-task1-review/validate_task1_review_docx.pyscript9.1 KB
scripts/ielts-task2-review/create_review_docx.pyscript34.3 KB
scripts/ielts-task2-review/extract_task2_input.pyscript9.8 KB
scripts/ielts-task2-review/validate_review_docx.pyscript9.1 KB
scripts/writing-revision-loop/create_revision_report_docx.pyscript13.9 KB
scripts/writing-revision-loop/validate_revision_report_docx.pyscript3.3 KB

references/ielts-task2-review/WORKFLOW.md

View on GitHub
# IELTS Task 2 Review

> 当当前学习任务需要本方法时按需读取。脚本命令中的 `scripts/` 相对于本 Skill 根目录;执行时解析为安装目录中的绝对路径。

## Core Rule

Imitate the teacher's marking style before giving generic IELTS advice. Use the teacher-style guide and the scoring guide as the two authorities:

1. Read `references/teacher_style.md` before reviewing.
2. Read `references/scoring_guide.md` before scoring.
3. Use `references/review_format.md` for the output structure.

## Requested document output

When the learner requests a Word review, deliver a validated reviewed `.docx`; otherwise provide the review in conversation.

1. Extract the prompt and scored essay.
2. Build the teacher-style review plan from the bundled references, the prompt, and the student's essay.
3. Generate the reviewed DOCX with `scripts/ielts-task2-review/create_review_docx.py`.
4. Validate it with `scripts/ielts-task2-review/validate_review_docx.py`.
5. Return the absolute path to the final reviewed DOCX. For a requested document, do not stop after presenting review text or JSON.
6. If validation fails, fix the review plan or document and rerun validation before delivery.

## IELTS Buddy Data Hand-off

IELTS Buddy currently exposes read-only writing records to external Agents. Keep local feedback and DOCX locally; formal submission and revisions remain in the browser.

Do not use a server operation that runs another teacher-style review. For rewrites, use `../writing-revision-loop/WORKFLOW.md` locally; formal browser submissions remain user-owned.

When the learner asks to keep useful corrections or expressions, follow [批改表达进入词汇本](../writing-vocabulary-handoff.md). Select evidence-backed reusable chunks and call `ielts_vocabulary_add` with `kind="word"` and `items: [{text, meaning}]` when the learner requests saving them.

## Workflow

1. Identify the Task 2 prompt and the student's essay.
   - Normal DOCX input should be an unreviewed student file containing the prompt, optional outline, and the student's essay.
   - For a `.docx`, first run `scripts/ielts-task2-review/extract_task2_input.py` to separate the prompt, optional outline, and student essay.
   - Preserve `student_essay_paragraph_indices` from the extraction result and include it in the review plan.
   - Treat short outline bullets after the prompt as planning notes, not as the scored essay.
   - Existing comments, italic rewrites, feedback, or model essays are not expected in normal use. If they are detected, treat them as accidental leftover material only; do not score, rewrite, or copy them as part of the student's essay.
   - For pasted text, separate prompt and essay from headings, blank lines, or explicit labels.
2. Check task fit before polishing language.
   - If the essay content, position, or logic is significantly off-topic, mark this first in comments.
   - Later italic rewrites and the final model essay must redirect the mistaken idea back to the task.
3. Calibrate comment style before writing comments.
   - Use `references/teacher_style.md` for short anchored comments and realistic Band 7.5 rewrites.
   - Use the prompt wording to identify the task type before judging task response.
4. Split the essay into review units.
   - Use sentence-level units when problems are local.
   - Use paragraph-level units when logic, task response, or coherence needs bigger repair.
5. Add teacher-style comments.
   - Comments must be short, Simplified Chinese, practical, and anchored to specific English words or phrases.
   - A non-empty comment target must match text inside the selected student essay paragraph; do not fall back to prompt, outline, or the whole wrong paragraph.
   - Prefer concrete notes: `偏口语`, `重复`, `不自然`, `可以更简洁`, `注意冠词`, `偏题`, `这里太笼统`.
6. Add italic rewrites after the relevant original unit.
   - Rewrites should be concise, formal, natural, and at a stable Band 7.5 standard.
   - Keep rewrites close to the student's intended meaning; avoid making local fixes sound like an over-polished Band 9 sample.
7. Score the student's original essay strictly using `references/scoring_guide.md`.
   - Score with bilingual learner-facing labels: 任务回应 Task Response, 连贯与衔接 Coherence & Cohesion, 词汇资源 Lexical Resource, 语法多样性与准确性 Grammatical Range & Accuracy, and 总分参考 Overall.
   - For this teacher-style educational review, criterion scores and the estimated overall score may use whole or half bands, such as `6`, `6.5`, or `7`. Use `.5` when the original essay sits between adjacent scoring anchors; do not force criterion scores to integers.
   - Do this before giving improvement advice.
8. Give concise Band 7.5 / 8.0-oriented feedback.
   - Separate issues blocking stable Band 7.5 from improvements needed to move toward 8.0.
   - Keep this section short and focused.
9. Write a 250-300 word model essay at a stable Band 8.0 standard.
   - Use exactly four paragraphs:
     1. Introduction: paraphrase the prompt and state the essay's position.
     2. Body paragraph 1.
     3. Body paragraph 2.
     4. Conclusion: begin with `In conclusion`.
   - Leave one blank line between model essay paragraphs in the output DOCX.
   - Align it with the scoring guide.
   - Preserve the student's main position when it is on-topic and defensible.
   - Correct any flawed or off-topic logic from the original draft.
   - It must be strong enough for Band 8.0: a clear and well-developed position, relevant and well-extended support, well-managed cohesion, flexible topic vocabulary, and mostly error-free grammar.
   - Keep it realistic and teacher-like, not an over-polished Band 9 essay.
10. Generate and validate a reviewed `.docx` by default.
   - For input `MyEssay.docx`, output `MyEssay(reviewed).docx` in the same folder unless the user specifies another path.
   - For DOCX input, create the reviewed file by copying the original DOCX first.
   - Write comments directly into the copied original essay paragraphs; do not create a second copy of the student's essay for comments.
   - Anchor comments only inside extracted student essay paragraphs, never inside prompt or outline paragraphs.
   - Insert italic rewrites immediately after the matched original essay paragraph.
   - Keep the original prompt and student essay in place; do not repeat the task prompt.
   - For pasted text, output to the current user's Desktop as `IELTS_Task2_Reviewed_YYYYMMDD_HHMM.docx`.
   - Use Times New Roman for all added review text and comments.
   - Use `Cyber Esme` as the Word comment author.
   - Do not add big visible section headings such as `Task`, `Reviewed Essay`, `Score`, or `Model Essay`.
   - Preserve the original `word/document.xml` root namespace declarations and `mc:Ignorable`; do not leave undeclared prefixes such as `w14`, `w15`, `w16*`, or `wp14`.
   - Insert a page break before the score and feedback page; keep the score lines and `冲刺 Band 7.5 / 8.0` together; insert another page break before the model essay.
   - Never overwrite the original essay unless explicitly requested.
11. Clean up temporary byproducts after a successful review.
   - Delete temporary review plan files such as `review_plan_c17t3.json`.
   - Prefer creating review plans in `系统临时目录` or use `--cleanup-plan` when running `scripts/ielts-task2-review/create_review_docx.py`.
   - Do not delete source essays, final reviewed `.docx` files, or bundled reference files.

## Bundled Resources

- `references/teacher_style.md`: teacher imitation rules for short anchored comments and rewrites.
- `references/scoring_guide.md`: concise, repository-owned Task 2 scoring guide.
- `references/review_format.md`: canonical reviewed document structure.
- `scripts/ielts-task2-review/extract_task2_input.py`: extract prompt, optional outline, and student essay from a Task 2 DOCX; it also protects against accidental leftover reviewed content.
- `scripts/ielts-task2-review/create_review_docx.py`: create a reviewed DOCX from a JSON review plan; DOCX input is copied first, comments are anchored into extracted student essay paragraphs, and score/model sections are appended.
- `scripts/ielts-task2-review/validate_review_docx.py`: verify comments, italic rewrites, student-essay paragraph comment anchoring when `--input-docx` is supplied, root namespace compatibility, score lines, retained `冲刺 Band 7.5 / 8.0` title, removed old headings, and model essay length/four-paragraph structure.

## JSON Review Plan For DOCX Creation

When using `scripts/ielts-task2-review/create_review_docx.py`, first produce a JSON file with this shape:

```json
{
  "prompt": "Task prompt",
  "student_essay_paragraph_indices": [12, 14, 16, 18],
  "review_units": [
    {
      "original": "Student sentence or paragraph.",
      "comments": [{"target": "specific phrase", "text": "中文短批注"}],
      "rewrite": "Italic teacher-style improvement."
    }
  ],
  "scores": {
    "任务回应 Task Response": "6.5",
    "连贯与衔接 Coherence & Cohesion": "7",
    "词汇资源 Lexical Resource": "6.5",
    "语法多样性与准确性 Grammatical Range & Accuracy": "6.5",
    "总分参考 Overall": "6.5"
  },
  "score_explanation": ["基于原文证据的简短中文评分说明。"],
  "focus_feedback": ["优先修正语法准确性和自然搭配。"],
  "model_essay": [
    "Paragraph 1: introduction with paraphrase and position.",
    "Paragraph 2: body paragraph 1.",
    "Paragraph 3: body paragraph 2.",
    "Paragraph 4: In conclusion, ..."
  ]
}
```

Scores are teacher-style estimates for the review output, so each criterion and `Overall` may be a whole band or a half band.

Then run:

```bash
python scripts/ielts-task2-review/create_review_docx.py review_plan.json --input-docx MyEssay.docx --cleanup-plan
python scripts/ielts-task2-review/validate_review_docx.py "MyEssay(reviewed).docx" --input-docx MyEssay.docx
```

For pasted text, omit `--input-docx` and the script will default to the Desktop output path.
If the review plan is a permanent example/reference file, omit `--cleanup-plan`.

## Quality Bar

- The reviewed DOCX must contain real Word comments, not plain bracketed notes.
- At least the most important local issues must be anchored to specific text.
- Italic rewrites must appear after the original unit and be written at a stable Band 7.5 standard.
- The score must evaluate the original essay, not the revised essay.
- The model essay must be exactly 4 paragraphs with one blank line between paragraphs, 250-300 words, and should stand securely at Band 8.0 according to the scoring guide.
- The style should follow `references/teacher_style.md`, not a generic IELTS tutor voice.
- Record locally judged criterion evidence as `rubric` with canonical Writing codes from `../skill-taxonomy.json`; keep band estimates and cited text in event details.
- Temporary files from the review process should be removed after successful validation.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall