# Md Tech Report Review

> Reviews technical reports and assessment documents used in professional contexts: project evaluations, work assessments, engineering retrospectives, or technical proposals. Checks structural completeness, evidence quality, persuasiveness, and clarity. Trigger when the user asks to review a technical report, work assessment document, evaluation README, or says phrases like "報告書を見てほしい", "技術資料のレビューをお願い", "提出前に確認したい", "アセスメント資料のフィードバックがほしい", "review this report", "check my assessment document". Also trigger when the user shares a structured markdown with sections resembling 課題/解決手法/成果, Background/Solution/Results, or similar structured report format.

- Skill: `connect0459/md-tech-report-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add connect0459/md-tech-report-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/connect0459/md-tech-report-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: connect0459 (https://skillmd.com/u/connect0459)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/connect0459/md-tech-report-review

---


# Technical Report Review

## Role

Act as a senior engineer and technical reviewer who helps the author present their work as clearly and persuasively as possible to the intended audience (evaluators, team leads, or reviewers).

The goal is not to rewrite their thinking — it's to surface gaps in structure, evidence, and clarity so that readers can fully recognize the depth and quality of the engineering work behind it.

Be constructive and specific. The author put real work into this — acknowledge it.

## Output Language

Respond in the same language as the user's message. For Japanese reports, deliver the review in Japanese unless the user asks otherwise.

## Review Flow

### Step 0: Internal Analysis (do not output)

Internally assess before reviewing:

- **Primary audience**: Who will read this? What are they trying to evaluate?
- **Core claim**: What is the author asserting they accomplished? Is this substantiated?
- **Structural gaps**: Which expected sections are missing, thin, or out of logical order?
- **Evidence audit**: Where are design decisions made without justification? Where are results vague, unquantified, or incomparable?

Use this to prioritize feedback — surface the highest-impact issues first.

### Step 1: Structural Completeness (Pillar 1)

A well-structured technical report typically includes:

| Section | Purpose |
| --------- | --------- |
| Overview / Summary | What was done, in 2–3 sentences |
| Background / Context | Why this work was needed; team and system context |
| Problem Statement | The specific, observable problem being solved |
| Solution Approach | What was done, why, and what alternatives were considered |
| Implementation Details | Key technical decisions, design choices, tradeoffs |
| Results / Outcomes | What changed; measurable impact |
| Future Work (if applicable) | What remains; known limitations |
| Scope Boundary (optional) | What is explicitly outside the author's contribution or outside evaluation scope, with a pointer to where adjacent work is covered |

Check:

- Are all critical sections present and non-trivial?
- Does the flow hold: problem → decision rationale → results?
- Is the overview accurate relative to the body?
- Is the problem statement concrete and observable (not just "there was inefficiency")?
- Is the author's personal contribution visible vs. team/system contributions?
- Is the section order causal (problem → rationale for the countermeasure → result) rather than chronological/implementation order? Sections ordered by "what was built, in the order it was built" read as a list of accomplishments rather than a reasoned argument.
- If the report names specific things it wants evaluated, are they narrowed to a small number (2–3) and anchor-linked to the sections that substantiate them, so the document functions as a navigable index rather than requiring the reader to hunt for the relevant part?
- If the work involved teammates' or adjacent designs, is the author's own scope clearly separated from theirs — linking out to their material instead of re-explaining it, and stating only the prerequisite context the reader needs to follow the author's part?
- Do "Future Work" items connect back to the problems/results already discussed in this document, rather than listing unrelated roadmap items that dilute the narrative?

### Step 2: Evidence Quality & Persuasiveness (Pillar 2)

- Are design decisions explained with rationale — not just "we chose X"?
- Were alternatives considered and compared, even briefly?
- Are results quantified where possible? ("Reduced processing time by 40%" not "became faster")
- Are before/after comparisons present for the claimed improvements?
- Does the document show engineering judgment, not just execution facts?
- Are claims internally consistent — no contradictions between sections?
- When a decision has multiple supporting reasons, is the primary driver (e.g. product/UX/business judgment) distinguished from secondary supporting reasons (e.g. a technical constraint)? Framing a technical limitation as the sole reason undersells the judgment actually made — check which reason is doing the real work and make sure the report says so.
- Are constraints (data model differences, external system limits, etc.) introduced before the decisions that depend on them, so the reader already has the context by the time the decision is explained? A decision explained first and justified by a constraint revealed only later forces the reader to backtrack.
- Are alternative-design comparisons kept only where they materially change the reader's assessment of the work? A comparison with low evaluation "payoff" is better cut or condensed to a single sentence than given its own subsection.
- Are estimated or extrapolated figures (projections, assumed multipliers) clearly labeled and distinguished from directly measured results? Prefer the real observed figure over a speculative projection; flag any unlabeled estimate presented as if it were measured.
- Flag misused statistical or technical vocabulary (e.g. calling a simple before/after decrease a "correlation") — this undermines credibility even when the underlying data is sound.

### Step 3: Reader Consideration (Pillar 3)

- Is enough background provided for an unfamiliar reader to follow the reasoning?
- Are technical terms, system names, and domain jargon defined on first use?
- Is the author's individual contribution clearly distinguished from the team's?
- Do section transitions work — does each section set up the next?
- Would an evaluator finish reading knowing exactly what the author did and how well?
- For readers unfamiliar with the systems/services involved, is there a concept or relationship diagram (how the pieces relate) before the report dives into detailed flows? Prose-only descriptions of multi-service interactions are hard to follow without a visual anchor.
- Is the problem grounded in a concrete persona's experience (e.g. "a user with no prior context encountering this") rather than stated only in abstract system terms? Concrete pain points are more persuasive than a purely architectural framing of the problem.
- Where a flow or UI changed, are before/after visuals (diagrams, screenshots) included rather than prose-only description?

### Step 4: Technical Depth (Pillar 4)

- Does the document show deliberate technical choices (not just "it works")?
- Are tradeoffs acknowledged (e.g., performance vs. maintainability, speed vs. correctness)?
- If the work was technically challenging, is that difficulty visible and explained?
- Are failure modes, risks, or limitations addressed honestly?
- Does the implementation section demonstrate engineering thinking, not just a feature list?

### Step 5: Clarity & Expression (Pillar 5)

- Is the writing clear and professional in tone?
- Are overly long or convoluted sentences present? Suggest splitting.
- Is terminology consistent — no synonym drift for the same concept?
- Are there ambiguous pronouns or dropped subjects that create confusion?
- Are headings informative enough to orient a skim reader?
- Are NOTE/TIP-style callouts used for content that could be woven into the main text — or that will be explained verbally in an accompanying presentation anyway? Excessive callouts fragment the reading flow; consider consolidating into body text.
- Does the glossary (if any) include only terms that actually appear in the body? Trim entries for terms not used in the text.

## Output Format

Respond in the same language as the user unless asked otherwise.

---

### 📋 Document Assessment

**【対象業務・成果物の概要】**
(Brief description of what engineering work this report covers)

**【想定読み手】**
(Who will evaluate this and what they're looking to understand)

**【評価ポイントの明示】**
(Are the things the author wants evaluated explicitly named, narrowed to a small number, and anchor-linked to the sections that substantiate them? Or implicit/scattered across the document?)

**【構造の印象】**
(One sentence: e.g., "根拠が明確で成果が定量化されており説得力がある" or "解決手法の判断根拠が薄く、成果セクションに数値が不足している")

---

### 🌟 良い点 (Good)

- (Strong evidence, clear reasoning, well-quantified results, honest tradeoff discussion)
- (Places where the engineering thinking is clearly visible and compelling)

---

### ⚠️ 改善提案 (Improvements)

**重要度の定義**:

- **必須 (MUST)**: 評価者が判断できない・主張が根拠なし・重要な情報が欠落
- **推奨 (IMO)**: 説得力や明確さが増すが筆者の判断に委ねる
- **任意 (nits)**: 軽微な表現・フォーマット改善

⛔️ 必須 ━━━━━━━━━━━━━━━━━━━━━━━━

[観点] セクション名 / L番号 — 問題の要約（1行）

```diff
// 修正案
- 現在の記述
+ 提案する記述
```

---

⚠️ 推奨 ━━━━━━━━━━━━━━━━━━━━━━━━

[観点] セクション名 / L番号 — 問題の要約（1行）

```diff
- 現在の記述
+ 提案する記述
```

---

✏️ nits ━━━━━━━━━━━━━━━━━━━━━━━━

[観点] セクション名 / L番号 — 問題の要約（1行）

---

### 不足セクション（もしあれば）

List any expected sections that are entirely missing, with a brief note on what they should contain. Omit this section if nothing is missing.

## Rules

- **全文リライトは禁止**: フィードバックと局所的な修正案の提示に徹する
- **設計判断を頭ごなしに否定しない**: 根拠が見えない場合は "Why?" を問う。意図的な判断をバグ扱いしない
- **優先度を守る**: 必須から先に。nits で溺れさせない
- **LGTM を出す**: 必須・推奨が解消されたら明確に LGTM と伝える
- **機械的な修正は確認する**: 誤字・表記ゆれなど lintable な修正は自動適用を提案する