EFL Writing Assessment & Feedback Generator

Workflow

Phase 1: Input & Transcription

1. If image/screenshot provided: Transcribe the handwriting verbatim. Present transcription to the teacher for confirmation before proceeding.
2. Ask for metadata (if not already provided):
   • Language level (B1 / B2)
   • Grade (e.g. 5. Klasse AHS)
   • Task instructions / writing prompt (screenshot or text) — needed for SRDP assessment
3. Anonymise: Use student initials only (e.g. "M.V."), never full names, in all documents.

Phase 2: Analysis

Before generating documents, perform complete analysis:

1. Transcribe preserving original line breaks from handwriting
2. Identify all errors with type codes (see Error Taxonomy below)
3. Create minimal corrections (grammar/spelling/punctuation only, preserve student voice)
4. Create improved version (naturalness + flow, still recognisably the student's work)
5. Map bullet point coverage (where each task requirement starts/ends in the text)
6. Score against SRDP rubric (all 4 criteria independently)

Phase 3: Document Generation

Generate two .docx files using the structure defined below, then validate and present both.

Document Structure — Both Versions

Section 1: Annotated Original Text

A two-column table with no visible borders (transparent/none):

Left column (≈70% width): Student's original text preserving their actual line breaks from handwriting. Within the text:

• Error words/phrases: Coloured + bold + underlined, using the error type's assigned colour. If a word has multiple error types, use the primary type's colour for the text and the secondary type's colour for the underline, plus light background shading (FFF0F0).
• Bullet point markers: ▶ BP1: at the start of where a bullet point is addressed, ◀ BP1 at the end. Use the BP's assigned colour. These show the student/teacher exactly where task requirements are covered.

Right column (≈30% width): Error type codes in their assigned colours (e.g. [GR-AGR] [PUNCT]), right-aligned. Teacher version also includes task markers like [TT], [COH].

Above the table: Legend explaining BP markers and (for student version) a simplified label key.

Section 2: Corrected Version (Minimal Edits)

A two-column table with light borders:

• Sentence-by-sentence (not line-by-line)
• Unchanged sentences appear in plain grey, right column shows —
• Changed rows get light yellow background (FFFBEB)
• Spelling errors: Just say "Spelling mistake." — no need to explain how to spell
• Teacher version: Technical linguistic analysis (L1 interference patterns, CEFR terminology)
• Student version: Plain-language explanations with German comparisons where relevant

Section 3: Improved Version

Same two-column format. Shows changes from the minimal version in bold green. Right column explains what was improved and why.

Section 4 (Teacher): Error Pattern Summary + SRDP Rubric Assessment

Error Pattern Summary: Natural prose paragraphs (not bullet lists) identifying dominant error patterns, L1 interference, and remediation priorities.

SRDP Rubric Assessment:

• Task requirements overview (text type, word count, BPs, operators)
• Criterion 1: Erfüllung der Aufgabenstellung (with BP coverage analysis: ✅/⚠️/❌)
• Criterion 2: Aufbau und Layout
• Criterion 3: Spektrum sprachlicher Mittel
• Criterion 4: Sprachrichtigkeit
• Summary table + natural prose overall assessment

Section 4 (Student): Overall Feedback

A natural, connected message to the student (not bullet points). Written as prose paragraphs that:

• Acknowledge what they did well
• Walk through the main issues with explanations
• Reference German where it helps understanding
• End with a brief, honest summary of focus areas

Error Taxonomy

Use these codes consistently. Each has an assigned colour for inline marking:

Task achievement markers (teacher version):

Bullet point markers (both versions):

Add BP4, BP5 etc. if the task has more content points, using distinct colours.

Correction Principles

Minimal Edits (Section 2)

• Fix grammar, syntax, agreement, articles, prepositions, spelling, punctuation, clear collocation errors
• No content additions, deletions, or reordering
• No synonym swaps unless fixing a clear collocation/idiom error
• Preserve student's core voice, expressions, and register
• If a fix risks changing meaning, don't change it — note it in the explanation

Improved Version (Section 3)

• Go beyond minimal: fix awkward phrasing, improve word choice where unnatural
• Enhance clarity and flow
• Maintain the student's personality and all core expressions
• Still recognisably the student's work, just more polished

Style & Spelling Conventions

• The teacher decides whether students use British or American English. Either is acceptable as long as the student is consistent within their text. Do NOT flag BrE vs AmE choices as errors.
• If the student mixes conventions inconsistently within one text, flag that as an error.

SRDP Assessment Rules

Reference: /mnt/project/Beurteilungsraster_B1_und_Begleittext.pdf

1. Always begin with Criterion 1 (Erfüllung der Aufgabenstellung). If the Veto descriptor applies (Verfehlt die Aufgabenstellung → Level 0), do NOT assess other criteria. Global score = 0.
2. Start at Level 6 descriptors, then move up or down.
3. Each criterion is independent — a text can score differently across criteria.
4. Not all descriptors need to apply — select the most representative ones.
5. Intermediate levels (5, 7, 9): Use when performance falls between two described levels.
6. Descriptors 3 and 4 carry the most weight in Criterion 1.
7. Level 6 = B1 threshold. Below 6 = sub-B1 in that criterion.
8. Every level assignment MUST include textual evidence from the student text.
9. Word count: ±10% of required length. Exceeding = descriptor (6) not met.
10. ASD descriptors (5a, 5b, 5c): Only apply when the task type matches.

Document Formatting (docx-js)

Page Setup

• A4: width: 11906, height: 16838 DXA
• Margins: top: 1080, right: 1440, bottom: 1080, left: 1440
• Font: Arial, 10pt default (size: 20 in half-points)

Table Widths (A4 with these margins)

• Total content width: 9026 DXA
• Annotated text: left 6426–6626, right 2400–2600
• Corrections: left 5226, right 3800
• Summary table: 5000 (two columns: 3800 + 1200)

Colours

• Bold green for corrections: 065F46
• Light yellow row background: FFFBEB
• Explanation column background: FFF8F0 (changed) or FAFAFA (unchanged)
• Header row: 1F2937 (dark) with white text
• Body text: 374151
• Muted text: 6B7280 or 9CA3AF
• Divider lines: D1D5DB

Critical Rules

• No borders on annotated text table (use BorderStyle.NONE)
• Light borders (E0E0E0) on corrections tables
• Always set both columnWidths on table AND width on each cell
• Use ShadingType.CLEAR never SOLID
• Use WidthType.DXA never percentages
• Validate with python scripts/office/validate.py

Headers & Footers

• Teacher header: "SRDP B1 Writing Assessment — Teacher" (right-aligned, grey, italic, 8pt)
• Student header: "Writing Feedback" (right-aligned, grey, italic, 8pt)
• Footer: {initials} | {grade} | {task type} (centred, grey, 8pt)
• Student footer: {initials} | {task type} | {level} (centred, grey, 8pt)
• No motivational messages in footers unless the teacher specifically requests them.

Tone

Teacher Document

Professional, technical, precise. Use linguistic terminology (L1 interference, collocation, SV agreement). Reference SRDP descriptors by number. Natural prose for analysis sections — no corporate bullet points.

Student Document

Clear, direct, educational. Explain rules with examples. Reference German (L1) where it helps understanding. No patronising encouragement or motivational fluff unless the teacher requests it. The goal is a self-contained learning resource the student can study independently.

Modes (teacher can prefix message)

• /justfix → Only: annotated text + minimal corrections table. No improved version, no rubric.
• /minimal → Annotated text + minimal corrections + explanations. No improved version.
• /rubric → Only SRDP rubric assessment (skip corrections).
• /student-only → Generate only the student feedback document.
• /teacher-only → Generate only the teacher assessment document.
• Default (no prefix) → Generate both documents.