Content
85%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a well-structured overview: a validated five-step workflow with a feedback loop, mostly executable PySpark examples, a crisp MUST DO/MUST NOT constraint list, and clean progressive disclosure into five real reference files. Its main weaknesses are the placeholder code in the caching example and trimmable sections (persona intro, Knowledge Reference list) that spend tokens on things Claude already knows.
Suggestions
Drop the 'Knowledge Reference' section and the persona intro line ('Senior Apache Spark engineer specializing in...') — they list concepts Claude already knows and spend context tokens without adding guidance.
Replace the placeholder code in the caching example ('df.filter(...).withColumn(...)') with concrete filter and withColumn calls so the pattern is copy-paste executable like the other examples.
Move the maintainer attribution and documentation link into the YAML frontmatter metadata to keep the body purely instructional.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean and instructional, but the 'Knowledge Reference' topic list ('Spark DataFrame API, Spark SQL, RDD transformations/actions, catalyst optimizer, tungsten execution engine...') and the persona intro line restate knowledge Claude already has and could be trimmed; not 3 because there is no significant padded explanation. | 4 / 5 |
Actionability | The quick-start pipeline, broadcast join, and salting examples are concrete and executable, but the caching example uses placeholder pseudocode ('df.filter(...).withColumn(...)') and the join snippets reference undefined variables, leaving minor gaps that keep it below fully copy-paste-ready. | 4 / 5 |
Workflow Clarity | The five-step Core Workflow ends with an explicit validation checkpoint ('Check Spark UI for shuffle spill before proceeding; verify partition count with df.rdd.getNumPartitions()') and an explicit feedback loop ('if spill or skew detected, return to step 4'), matching the anchor for clear sequence with validation and error recovery. | 5 / 5 |
Progressive Disclosure | The Reference Guide table provides well-signaled, one-level-deep references with a 'Load When' column, and all five referenced files (spark-sql-dataframes.md, rdd-operations.md, partitioning-caching.md, performance-tuning.md, streaming-patterns.md) exist in references/, giving clear overview-plus-detail navigation. | 5 / 5 |
Total | 18 / 20 Passed |