zh-ebn-report

Evidence-Based Nursing Report Coach for Taiwan

This skill helps Taiwanese nursing staff complete evidence-based reports that meet the review standards of the Taiwan Nurses Association and the Taiwan Evidence-Based Nursing Association, coveringevidence-based reading reportsandevidence-based case analysestwo types. The ultimate goal is to help nurses pass the N2/N3/N4 advancement review, or produce submittable academic work.

What report types does this skill cover

The Taiwanese evidence-based nursing community mainly divides into two entry-level types:

Type	Difference	Corresponding level	Length
Evidence-based reading report（EBR）	After appraising several articles, perform a logical synthesis,no case application	mainly N1, N2	approximately 8–15 pages
Evidence-based case analysis（EBP case analysis）	Apply evidence-based resultsto one real patientand evaluate the effectiveness	N3 and above	approximately 15–25 pages

N4 and above mostly have already entered systematic literature reviews or nursing project research, which this skill does not cover.

Identity confirmation before writing

Before starting to write, first clarify the following four things with the user, to determine which template and depth to use:

1. Which type of report is to be written?(reading report / case analysis)
2. Which advancement level is it?(N1–N4, or submission competition)
3. What are the ward type and case conditions?(determines the reasonableness and feasibility of the topic)
4. Does the hospital have a dedicated format template?(if so, the hospital template prevails, and this skill supplements the content)

If these are not yet confirmed,do not rush to draft, first use the ask_user_input_v0 tool to ask.

Core workflow: the evidence-based 5A steps

All evidence-based reports revolve around these five steps, none of which can be omitted (reading reports may stop at Appraise; case analyses must complete all five steps):

1. Ask — Form an answerable clinical question (PICO)
2. Acquire — Search for the best literature evidence
3. Appraise — Rigorously appraise the evidence (CASP + Oxford levels of evidence)
4. Apply — Apply clinically to the case (case analysis only)
5. Audit — Evaluate the results (case analysis only)

For detailed operation methods, common errors, and sentence pattern examples for each step, see the corresponding reference file.

Automated Pipeline and HITL reviewer role division

This skill works with the zh-ebn-report Python CLI (located at the project root's src/zh_ebn_report/), with 10 named subagents dividing the work to complete the report draft. The user's role shifts from "writer" to "HITL reviewer"] — Intervene, approve, or request rewrites at 9 checkpoints; the final text must still be rewritten in one's own words for submission (academic ethics remain unchanged).

Subagent division of labor(see details in references/subagent-roles.md）：

#	Role	Parallel?
1	Topic gatekeeper	No
2	PICO constructor	No
3	Search strategist	No
4	CASP appraiser × N	Yes
5	Synthesis integrator	No
6	Section writer × 4–6	Yes
7	Tone gatekeeper	Parallel with 8
8	APA 7 formatter	Parallel with 7
9	Case narrator (case analysis)	Parallel with 10
10	Application auditor (case analysis)	Parallel with 9

Dispatch principle: agents whose inputs do not depend on each other should alwaysrun in parallelbe called in parallel (Phase 4 multiple CASP appraisals, Phase 6 each section, Phase 7 tone + APA, Phase 5.5 case + application). In interactive assistance scenarios, Claude should adopt the same logic.

CLI interface：

zh-ebn-report init --type reading|case --topic "..."
zh-ebn-report run  --resume <run-id>              # end-to-end
zh-ebn-report topic|pico|search|appraise|synthesise|write|check|render
zh-ebn-report render --final                        # 去 DRAFT 後綴（需已 review）
zh-ebn-report status <run-id>

LLM backend (v0.6+): by default the pipeline uses the Claude Code CLI (your Claude subscription), and no longer forces ANTHROPIC_API_KEY. Switch via the LLM_BACKEND environment variable:

• LLM_BACKEND=claude_code(default) — calls via subprocess claude -p, using your subscription. Requires claude CLI
• LLM_BACKEND=anthropic — goes directly through the Anthropic SDK; requires ANTHROPIC_API_KEY(or LLM_API_KEY), suitable for CI or environments without a subscription
• LLM_BACKEND=auto — detects whether claude CLI is present, then chooses

Implementation see clients/llm.py（Protocol + factory）、clients/claude_code_cli.py(CLI backend),clients/anthropic.py(SDK backend). The two backends have consistent external interfaces, andcomplete() / complete_json() can be swapped interchangeably. Concurrency: multiple LLM calls spawn multiple claude subprocesses, with rate limiting by config such as max_parallel_casp .

Guardrail architecture (v0.2+): the pipeline no longer relies only on LLM self-discipline. Every "hard rule" written in the prompt for an LLM, as long as it is mechanically verifiable, has a corresponding Python guardrail in the orchestrator that overrides the LLM's self-assessment result, or blocks it in compliance.check_sections :

• pipeline/evidence_guard.py — Oxford Level must not exceed the OCEBM 2011 ceiling of the study_design (MA-of-cohort must never be Level I)
• pipeline/synthesis_guard.py — overall_evidence_strength mechanically derived from CASP levels + contradictions
• pipeline/voice_scan.py — regex scans banned words and recalculates pass_threshold_met
• pipeline/apa_guard.py — apa_pass derived from DOI validation + citation existence + LLM format_issues
• pipeline/compliance.py — sentence patterns, word count, quotations, anonymization, privacy, absolute terms, citation fabrication defenses

Regression validation tool: run after each addition or modification of a guardrail:

python scripts/retro_validate.py

Load all historical data from output/<run-id>/state.json , apply the current guardrails to all of it, and report "what would have been caught if these guardrails had existed at the time." Used to (a) confirm that guardrails catch real violations, and (b) avoid regressions. Add --json to output for CI; add --strict to make any guardrail finding exit with code 1.

Taiwan nursing enhancement (v0.8+): dedicated support for three core needs of Taiwan nursing practice.

1. Airiti Import: Added CSV support in addition to RIS (Airiti's default bibliographic export format).

   • zh-ebn-report search <run-id> --airiti-csv <file.csv> — Reads title/author/year/journal/DOI/abstract/type
   • Automatically detects "thesis" and fixes StudyDesign.OTHER + OxfordLevel.IV(theses are not peer-reviewed and must not be upgraded in level)
   • Chinese author names (張小明 and other pure CJK strings) automatically use the first 2 characters as the citekey surname, resolving the previous split() mis-splitting issue
   • Export steps: Go to Airiti Library → check the references → Bibliography Management → select CSV export → download
   • Implementation see clients/manual_import.py:_airiti_csv_to_records

2. Gordon's 11 Functional Health Patterns: TWNA case report / nursing project 護理評估 section's standard skeleton.

   • Reference:references/gordon-11-patterns.md(11 pattern definitions + subjective/objective data templates + NANDA diagnosis cross-reference)
   • Writing role:prompts/section_writer_護理評估.md, requiring the LLM to produce S/O + assessment findings item by item
   • Compliance：_check_gordon_11_coverage scans the 護理評估 section for coverage of ≥ 9/11 key patterns (flexible threshold; pattern 9 - sexuality-reproduction may be omitted in acute/pediatric contexts)
   • Only triggered for twna_case / twna_project type; not mandatory for reading/case types

3. AI keyword adjustment (keyword tuner): If the initial PubMed search falls outside the 100–1000 "sweet spot", an optional round of LLM adjustment can be enabled.

   • Enable:ENABLE_KEYWORD_TUNER=1(default off)
   • Trigger condition: first-round hits < 50 (too narrow) or > 5000 (too broad)
   • Adjuster:prompts/keyword_tuner.md(Haiku tier, only modifies the Boolean string)
   • Decision:pipeline/keyword_tuner.pick_better picks the version closer to the sweet spot;SearchHistoryRow.note both rounds are recorded, visible for audit
   • Maximum 1 round; if the second round still falls outside, accept the current state and do not call the tuner again (cost control)

Audit Artifact Store（v0.7+）: Each run leaves in output/<run-id>/artifacts/ a full set of intermediate artifacts for future review:

artifacts/
  _index.jsonl                  # append-only 所有 artifact 的紀錄（timestamp, category, path, meta）
  blobs/<sha256>.txt            # 內容定址儲存（system prompt 60KB × 30 次只存 1 份）
  llm/<ISO>_<caller>_<tier>_<id>.json  # 每次 LLM 呼叫的完整記錄
  guardrails/<name>/<ISO>_{before,after,summary}.json  # 每道 guardrail 的 before/after/summary

The LLM record contains: caller function name (auto-detected from stack), tier, model, backend (anthropic / claude_code), duration_ms, system prompt hashes, user msg hash, response raw hash, response_parsed. Guardrail records preserve both versions: "LLM original interpretation vs Python-overridden".

Implementation see pipeline/audit.py（ArtifactStore) and clients/audited.py（AuditedLLMClient). The Orchestrator calls _bind_to_run(state) at each phase entry to create the store for the corresponding run; LLM and guardrail calls are transparently logged.

Pipeline final output <報告>-DRAFT.docx(Quarto → pandoc → DOCX, APA 7 CSL citation formatting), including search history table, CASP appraisal table, PRISMA-style flow diagram, AI collaboration statement page. If templates/reference.docx(optional) exists, it will be used as the style template to apply institutional fonts and styles; otherwise output uses pandoc's default style.

Code of Ethics(per 2026 Taiwan Nurses Association and Taiwan Evidence-Based Nursing Association regulations; see references/ai-disclosure.md）：

• AI can fully generate the draft, butthe user must audit, disclose, and take responsibility
• CLI startup must pass the --i-accept-audit-responsibility flag; if not passed, it will not execute
• The Pipeline automatically attaches three required documents:AI usage disclosure paragraph(methods/acknowledgments),Audit responsibility statement(cover page or last page),Subagent execution record(supplementary material)
• The filename is prefixed with -DRAFTby default; after the user completes the review and explicitly checks "Reviewed", use render --final to remove the suffix
• AI must not be listed as an author; the disclosure paragraph must state the tool name, model, version, and specific manner of use

Process for using this skill

Based on the stage the user is at, provide assistance in the following order:

Scenario A: The user is still selecting a topic

First read references/topic-selection.md, and help the user judge whether the topic is feasible. Avoid the five major landmine topics (very little literature, too controversial, ethically sensitive, not operable, not within the scope of nursing expertise).

Dispatch at this stage: Topic Gatekeeper (Subagent 1) → CP1.

Scenario B: The user already has a topic and wants to set up a PICO

Read references/pico-and-search.md, apply the PICO structure, and note:

• Chinese and English in parallel(reviewers want to see English keywords)
• Specify thequestion type(Therapy / Harm / Diagnosis / Prognosis)
• Outcomes should be quantified and observable as much as possible

Dispatch at this stage: PICO Builder (Subagent 2) → CP2.

Scenario C: Conducting a literature search and critical appraisal

Read references/pico-and-search.md(search strategy) and references/appraisal-tools.md(appraisal tools and levels of evidence).

Key reminders:

• The search process must be reproducible: database, keywords, Boolean logic,field codes, Limits, initial number of records,number of records after deduplication, exclusion criteria, and number of included records must all be accounted for
• Six-piece search strategy: subject terms / synonyms / MeSH / CINAHL Heading / Boolean / field codes
• The initial number of records has a sweet spot of 100–1000; if outside this range, record the iterative adjustments
• Citation tracking: both forward (Google Scholar "Cited by") and backward (reference list) have been done
• DOI verification record by record(the pipeline automatically uses CrossRef; manually you can use https://doi.org/<DOI>）
• Appraisal tools correspond to study designs: use CASP RCT for RCTs, CASP SR for systematic reviews, and JBI for qualitative studies
• Levels of evidence follow the Oxford 2011 criteria

Dispatch at this stage: Search Strategist (3) → CP3 → CP4 → CASP Appraisers × N in parallel (4) → CP5.

Scenario D: Applying evidence-based results to a case (the core of case analysis)

Read references/case-report-template.md. Note the requirements unique to nursing reports:

• There must bethe nurse's own wordsas direct quotations
• There must bethe case/family member's own wordsas direct quotations (in quotation marks)
• There must bespecific time pointsin the assessment records
• Results must beobjectively measurable + subjective feelingspresented together
• Case datamust already be de-identified(all names, medical record numbers, and ID numbers removed) before entering this stage

Dispatch for this stage: Integrator (5) → CP6 → Case Narrator + Application Auditor (9, 10) in parallel → Section Writers × 6 in parallel (6) → CP7.

Scenario E: Need to write the conclusion and discussion

Read references/phrasing-bank.md. Standard actions for the conclusion section:

1. Conclusion responding to the PICO
2. Acknowledge study limitations
3. Local context considerations (cannot hastily overturn nursing routines across the board）
4. Recommendations for future clinical practice and education

Dispatch for this stage: Section Writer (6, conclusion section) → Tone Gatekeeper + APA 7 Formatter (7, 8) in parallel → CP8 → Quarto render → CP9.

Core rules of writing style

Taiwanese evidence-based nursing reports have a very fixed "tone"; if you don't conform, you'll be seen as an outsider. Core principles:

Refer to yourself as "the author", not "I".

Do not call the case a "patient"; call them "the case" or "Case ○" (case mother, case father, case brother, etc.).

Verbs lean toward formal written language：

• Don't write "I looked up a few articles" → write "relevant literature was retrieved using evidence-based methods"
• Don't write "the patient said he didn't want to lie down" → write "the case complained of being unable to cooperate with prolonged supine positioning"
• Don't write "I think it should be done this way" → write "integrating the evidence-based results, it is recommended that..."

In the reference list, Chinese sources come before English ones, following APA 7th edition format. Chinese sources are ordered by surname stroke count, English sources alphabetically.

Cite literature from the past 5 years as much as possible, unless it is an important classic study.

For more sentence pattern examples, see references/phrasing-bank.md。

Writing strategies with the highest review pass rates

Based on templates that have passed over the years, the following practices most improve pass rates:

1. The topic must be specific, not grand. "How to reduce postoperative infection" will be rejected; "Comparison of the effects of chewing gum versus usual care on recovery of bowel motility in adults after abdominal surgery" will pass.

2. The search process should be as transparent as possible. Present in a table: database / keywords / initial number of articles / exclusion criteria / number of articles included.

3. Include at least 2–4 articles with a high level of evidence. Mainly Oxford Level I–II (RCT, SR, MA). If literature is extremely scarce, it may be relaxed to observational studies, but this must be explained in the discussion section.

4. The CASP appraisal table must be attached in full; you cannot just write vague language like "the validity of this article is acceptable."

5. The case analysis must have a real record of application. Reviewers most dislike seeing overly perfect narratives such as "planned to do it but didn't" or "the application results were completely consistent with the literature." Deviation is what's reasonable, and deviations must be explainable.

6. The discussion section must reflect reflection. Don't just say "the evidence-based results are great, we'll do it this way from now on." Acknowledge local limitations, institutional culture, and individual differences.

7. New norms for AI collaboration (2026 version): The Taiwan Nurses Association and the Taiwan Evidence-Based Nursing Association have explicitly permittedthe use of generative AI to assist writing, on the condition that:

   • AI must not be listed as an author
   • It must be in the research methods or acknowledgments sectionactively disclosed AI tool name, version, and specific method of use
   • The author mustreview and revise section by section the content produced by AI
   • The author must declare: "I have reviewed and revised the content produced by GenAI, and I take full responsibility for the truthfulness and accuracy of the content of this article."
   • It is recommended to submit the AI-assisted generated portions together as supplementary material

   In other words:AI can help you turn a vague topic into a good topic and generate a complete draft, butyou must read it, revise it, and sign to take responsibility. The goal of this skill is to provide an AI collaboration pipeline that complies with this specification (see references/ai-disclosure.md）。

Common pitfalls and mistakes

• Writing the Comparison in PICO incorrectly. Comparison is not "no intervention," but "current standard of care" or "another intervention."
• Writing an evidence-based reading report as a general literature review. A reading report requires critical appraisal, synthesis, and conclusions and recommendations, not merely a summary of the literature.
• Marking evidence levels incorrectly. The Oxford 2011 version is currently mainstream; do not use the old 1–4 levels.
• Checking boxes on the CASP form without explanation. Each question requires a brief explanation, especially items marked "unclear."
• Exposure of case data. Names, medical record numbers, and specific identifying characteristics must be de-identified.
• References not using APA 7th edition. After 2020, always use APA 7, not APA 6.

Reference file index

This skill includes the following reference files, to be loaded as needed:

• references/case-report-template.md — Complete template for evidence-based case analysis (most commonly used)
• references/reading-report-template.md — Evidence-based reading report template
• references/pico-and-search.md — PICO formulation and literature search strategy (including the six-piece set, field codes, 100–1000 calibration, citation tracking, DOI verification)
• references/appraisal-tools.md — CASP appraisal form and Oxford evidence levels
• references/phrasing-bank.md — Taiwan nursing report standard sentence pattern library
• references/topic-selection.md — Topic selection guidelines and landmine topics
• references/subagent-roles.md — Division of labor and input/output contracts for 10 subagents (corresponding to the Python pipeline)
• references/ai-disclosure.md — Three templates for the 2026 Taiwan nursing AI usage specification and disclosure/audit/subagent records
• references/gordon-11-patterns.md — Gordon's 11 functional health patterns (standard skeleton for the TWNA nursing assessment section)

After seeing the user's needs,first decide which reference files to read, and do not stuff them all into the context.

Final output

After completing the draft, provide:

1. A complete report document(recommended in .docx format, because hospitals mostly require paper submissions)
2. A standalone reference list(for checking APA format)
3. A table of the search history(for the appendix)
4. A CASP appraisal form(for the appendix)

If the user also needs a slide version (for oral presentation), provide an outline for a 15-minute presentation: clinical scenario 2 min → PICO and search 3 min → evidence summary 5 min → application results 4 min → conclusions and recommendations 1 min.

---

Remember:The value of this skill lies in enabling AI and human nurses to collaborate in producing evidence-based reports that can pass review. According to the 2026 regulations of the Taiwan Nurses Association and the Taiwan Evidence-Based Nursing Association, AI may assist in generating a complete draft; human nurses use HITL checkpoints to audit section by section, revise, add personal clinical observations, and sign to take responsibility. The final submission document must include an AI use disclosure paragraph and an Audit responsibility statement (see references/ai-disclosure.md）。