workshop-review-technical - SKILL.md Agent Skill

name: workshop-review-technical description: Review workshop content for technical accuracy disable-model-invocation: true allowed-tools: Read, Edit, Write, Glob, Grep, Bash

Workshop Review: Technical Accuracy

Purpose: Review workshop content for technical accuracy, query correctness, and Neo4j best practices.

When to use: After pedagogy review is complete and content is ready for technical validation.

Prerequisites:

Workshop content is complete
Grammar review completed
Pedagogy review completed
Access to Neo4j instance for testing

Overview

This skill performs a technical accuracy review that checks:

Cypher query syntax and correctness
Property naming consistency
Neo4j best practices
Verification files functionality
SQL comparisons accuracy
Tool references correctness
Data model accuracy

This review focuses on TECHNICAL CORRECTNESS, not pedagogy or grammar.

Phase 1: Pre-Review Setup (10 min)

Checklist: Preparation

Read WORKSHOP-PLAN.md for technical details
Set up Neo4j instance for testing
Load workshop data files
Review data model
Create review tracking document

Setup Test Environment

Required:

Neo4j Aura Free instance (or local Neo4j)
Workshop data files downloaded
Data model imported
Access to Query tool

Preparation steps:

Create fresh Aura instance
Import workshop data using Data Importer
Verify all nodes/relationships exist
Ready to test queries

Create Tracking Document

Create TECHNICAL-REVIEW-PROGRESS.md:

# Technical Review Progress

**Workshop:** [Name]
**Reviewer:** Technical Review Skill
**Date:** [Date]
**Test Instance:** [URL or name]

## Data Model Verification

- [ ] Products: [N] nodes
- [ ] Customers: [N] nodes
- [ ] Orders: [N] nodes
- [ ] Relationships verified

## Review Status

### Module 1: [Name]
- [ ] Lesson 1 - Technical review
- [ ] Lesson 2 - Technical review
- [ ] Lesson 3 - Technical review

[Continue for all modules...]

## Issues Found
- Query error: [Description]
- Property naming: [Description]

## Review Complete
- All queries tested: Yes/No
- All verify.cypher files tested: Yes/No
- SQL comparisons verified: Yes/No

Phase 2: Data Model Review (20 min)

Checklist: Data Model

All node labels documented
All relationship types documented
Property names consistent
Property types correct
Data constraints understood
Sample data loaded

Data Model Validation

Verify the data model matches workshop:

// Check node counts
MATCH (n)
RETURN labels(n) AS label, count(n) AS count;

// Check relationship types
MATCH ()-[r]->()
RETURN type(r) AS type, count(r) AS count;

// Check properties on nodes
MATCH (n)
RETURN DISTINCT labels(n) AS label,
       [key IN keys(n) | key] AS properties
LIMIT 1;

// Check properties on relationships
MATCH ()-[r]->()
RETURN DISTINCT type(r) AS type,
       [key IN keys(r) | key] AS properties
LIMIT 1;

Document findings:

## Data Model

### Nodes
- `Product`: [N] nodes
  - Properties: id, name, unitPrice, unitsInStock
- `Customer`: [N] nodes
  - Properties: id, name, city, country
- `Order`: [N] nodes
  - Properties: id, date, total

### Relationships
- `PLACED`: Customer → Order ([N] relationships)
- `ORDERS`: Order → Product ([N] relationships)
  - Properties: quantity, unitPrice

Issues to flag:

Missing expected nodes/relationships
Property names inconsistent
Property types wrong
Data not loaded

Phase 3: Query Testing (Per Lesson)

Checklist: Query Testing

All Cypher queries run without errors
Queries return expected results
Property names match data model
Query syntax follows best practices
Performance is reasonable

Query Testing Process

For each Cypher query in lessons:

Copy query from lesson
Run in Query tool
Verify:
- No syntax errors
- Returns results (or appropriate empty set)
- Results match lesson description
- Property names correct
Check best practices:
- Uses pattern matching appropriately
- Avoids anti-patterns
- Performance is reasonable

Common Query Issues

Issue 1: Property naming

❌ Wrong property names:

MATCH (c:Customer {customerId: 'ALFKI'})
RETURN c.companyName;

✅ Correct property names:

MATCH (c:Customer {id: 'ALFKI'})
RETURN c.name;

Issue 2: Case sensitivity

❌ Wrong case:

match (c:customer) return c.Name;

✅ Correct case:

MATCH (c:Customer) RETURN c.name;

Issue 3: Syntax errors

❌ Missing semicolon or wrong syntax:

MATCH (c:Customer)
WHERE c.id = ALFKI  // Missing quotes
RETURN c.name

✅ Correct syntax:

MATCH (c:Customer)
WHERE c.id = 'ALFKI'
RETURN c.name;

Issue 4: Anti-patterns

❌ OPTIONAL MATCH for counts:

MATCH (c:Customer)
OPTIONAL MATCH (c)-[:PLACED]->(o:Order)
RETURN c.name, count(o);

✅ COUNT subquery:

MATCH (c:Customer)
RETURN c.name, COUNT { (c)-[:PLACED]->(:Order) } AS orderCount;

Phase 4: Verification Files Testing (Per Challenge)

Checklist: Verification Files

verify.cypher exists
verify.cypher runs without errors
verify.cypher returns outcome and reason
verify.cypher handles edge cases
solution.cypher exists
solution.cypher runs without errors
solution.cypher passes verification

Verification File Testing Process

For each challenge lesson:

Test verify.cypher
- Run in Query tool
- Returns exactly 2 columns: outcome, reason
- outcome is boolean
- reason is helpful message
Test with no data
- Delete nodes: MATCH (n:NodeLabel) DETACH DELETE n
- Run verify.cypher
- outcome should be false
- reason should explain what's missing
Test with partial data
- Create some but not all expected nodes
- Run verify.cypher
- outcome should be false if incomplete
- reason should indicate partial import
Test with complete data
- Import all expected data
- Run verify.cypher
- outcome should be true
- reason should confirm success
Test solution.cypher
- Start with empty database
- Run solution.cypher
- Run verify.cypher
- outcome should be true

Example Verification Testing

// Test 1: No data
MATCH (n:Product) DETACH DELETE n;

// Run verify.cypher - should return:
// outcome: false
// reason: "No Product nodes found. Make sure you ran the import..."

// Test 2: Partial data
CREATE (:Product {id: "1", name: "Test"});

// Run verify.cypher - should return:
// outcome: false
// reason: "Only 1 Product nodes found. Expected 77."

// Test 3: Complete data
// (Import full dataset)

// Run verify.cypher - should return:
// outcome: true
// reason: "Success! You imported 77 Product nodes."

// Test 4: Solution passes
MATCH (n:Product) DETACH DELETE n;

// Run solution.cypher
// Run verify.cypher - should return:
// outcome: true

Issues to flag:

verify.cypher doesn't return outcome and reason
verify.cypher crashes with errors
Error messages not helpful
solution.cypher doesn't pass verification
verification doesn't handle edge cases

Phase 5: SQL Comparison Validation (Per Validation Lesson)

Checklist: SQL Comparisons

SQL queries are syntactically correct
SQL queries return same results as Cypher
SQL queries are fair (not intentionally bad)
Comparisons are accurate (lines, JOINs counted correctly)
Metrics are defensible

SQL Comparison Testing Process

For each SQL comparison:

Verify SQL syntax
- SQL query is valid
- Would run in a relational database
- Uses appropriate dialect (PostgreSQL, MySQL, etc.)
Verify equivalence
- SQL produces same results as Cypher
- Row counts match
- Columns match
- Data values match
Verify fairness
- SQL is reasonable (not intentionally verbose)
- Uses appropriate JOINs and indexes
- Represents what a competent SQL developer would write
Verify metrics
- Line count accurate
- JOIN count correct
- Complexity claims defensible

Example SQL Validation

Cypher query:

MATCH (c:Customer {id: 'ALFKI'})
      -[:PLACED]->(:Order)
      -[:ORDERS]->(p:Product)
RETURN DISTINCT p.name;

SQL equivalent:

SELECT DISTINCT p.productName
FROM customers c
JOIN orders o ON c.customerId = o.customerId
JOIN order_details od ON o.orderId = od.orderId
JOIN products p ON od.productId = p.productId
WHERE c.customerId = 'ALFKI';

Validation:

SQL syntax correct: ✅
Returns same products: ✅
Fair representation: ✅
Metrics: 4 lines vs 7 lines ✅, 0 JOINs vs 3 JOINs ✅

Issues to flag:

SQL syntax errors
SQL doesn't return same results
SQL is intentionally bad/verbose
Metrics are inaccurate (wrong JOIN count, wrong line count)
Complexity claims not defensible

Phase 6: Property Naming Consistency (Cross-Lesson)

Checklist: Property Names

All queries use id (not customerId, productId)
All queries use name (not companyName, productName)
All queries use date (not orderDate)
Property names match import configuration
Consistent across all lessons

Property Naming Validation

Standard property names:

id - for all entity identifiers
name - for all entity names
date - for order dates
total - for order totals
city - for customer city
country - for customer country
unitPrice - for product prices
quantity - for order quantities

Search all lessons for:

# Bad patterns to find
customerId
productId
orderId
companyName
productName
orderDate

Should be:

id
id
id
name
name
date

Issues to flag:

Inconsistent property names across lessons
Using old property names (customerId instead of id)
Property names don't match data model

Phase 7: Neo4j Best Practices Review

Checklist: Best Practices

Uses COUNT subqueries (not OPTIONAL MATCH for counts)
Uses pattern comprehensions for nested values
Appropriate use of indexes (if mentioned)
No Cartesian products
LIMIT used appropriately
No anti-patterns

Best Practice Validation

Pattern 1: COUNT subqueries

❌ Anti-pattern:

MATCH (c:Customer)
OPTIONAL MATCH (c)-[:PLACED]->(o:Order)
RETURN c.name, count(o);

✅ Best practice:

MATCH (c:Customer)
RETURN c.name, COUNT { (c)-[:PLACED]->(:Order) } AS orderCount;

Pattern 2: Pattern comprehensions

❌ Verbose:

MATCH (c:Customer)-[:PLACED]->(o:Order)
WITH c, collect(o.id) AS orderIds
RETURN c.name, orderIds;

✅ Concise:

MATCH (c:Customer)
RETURN c.name,
       [(c)-[:PLACED]->(o:Order) | o.id] AS orderIds;

Pattern 3: Cartesian products

❌ Accidental Cartesian:

MATCH (c:Customer), (p:Product)
WHERE c.country = 'USA'
RETURN c.name, p.name;

✅ Intentional or avoided:

MATCH (c:Customer)-[:PLACED]->(:Order)-[:ORDERS]->(p:Product)
WHERE c.country = 'USA'
RETURN c.name, p.name;

Issues to flag:

Use of OPTIONAL MATCH for counts
Accidental Cartesian products
Missing LIMIT on queries that could return thousands
Anti-patterns that should be updated

Phase 8: Tool Reference Accuracy

Checklist: Tool References

Module 1 Lesson 3 is tool mechanics source of truth
Later lessons reference Module 1 Lesson 3 (not repeat mechanics)
Tool names correct (Data Importer, Query tool, Explore)
Screenshots match current UI
Button text accurate

Tool Reference Validation

Module 1 Lesson 3 should have:

Comprehensive Data Importer walkthrough
Query tool introduction
Explore tool introduction
Screenshots of each tool

All other lessons should:

Reference Module 1 Lesson 3 for mechanics
NOT repeat step-by-step UI instructions
Focus on WHAT to do, not HOW to click

Example good reference:

[.slide]
== Using Data Importer

**Reference:** See Module 1 Lesson 3 for Data Importer mechanics.

**Steps for this challenge:**
1. Upload products.csv
2. Map to Product node
3. Configure properties (table below)
4. Run import

Example bad reference (repeating mechanics):

[.slide]
== Using Data Importer

1. Click "Import" in the Aura console
2. Click "Add Data"
3. Click "Upload File"
4. Navigate to products.csv
5. Click "Open"
[... 20 more steps ...]

Issues to flag:

Lessons repeat tool mechanics
Don't reference Module 1 Lesson 3
Tool names incorrect
Screenshots outdated

Phase 9: Building Block Technical Validation

Checklist: Building Block Verification

Each challenge actually completes what it claims
Verification confirms building block
Data model matches building block description
Building blocks can be tested independently

Building Block Testing

For each building block:

Read the claim:
- "Building Block 1: Products exist in the graph ✓"

Verify technically:

// Test: Do products exist?
MATCH (p:Product)
RETURN count(p) AS productCount;
// Should return 77

Verify completeness:

// Test: Do products have required properties?
MATCH (p:Product)
RETURN p.id, p.name, p.unitPrice, p.unitsInStock
LIMIT 1;
// Should return all properties

Verify usability:
- Can this building block be used in next module?
- Are the right relationships/properties in place?

Example building block tests:

// Building Block 2: "Customer→Order path complete"
MATCH path = (c:Customer)-[:PLACED]->(o:Order)
RETURN count(path) AS pathCount;
// Should return number of orders

// Building Block 3: "Customer→Order→Product path complete"
MATCH path = (c:Customer)-[:PLACED]->(:Order)-[:ORDERS]->(p:Product)
RETURN count(path) AS pathCount;
// Should return number of order line items

Issues to flag:

Building block claim doesn't match reality
Data model incomplete for claimed building block
Building block can't be used as described

Phase 10: Final Technical Report

Create Review Summary

Update TECHNICAL-REVIEW-PROGRESS.md with results:

# Technical Review Complete

**Workshop:** [Name]
**Date Completed:** [Date]
**Test Instance:** [URL]

## Summary Assessment

### Data Model: ✅ Pass / ❌ Fail
- All nodes present: [Yes/No]
- All relationships present: [Yes/No]
- Property names consistent: [Yes/No]

### Query Accuracy: ✅ Pass / ❌ Fail
- All Cypher queries tested: [N/N]
- All queries run without errors: [Yes/No]
- Queries return expected results: [Yes/No]

### Verification Files: ✅ Pass / ❌ Fail
- All verify.cypher tested: [N/N]
- All return outcome + reason: [Yes/No]
- All solution.cypher pass verification: [Yes/No]

### SQL Comparisons: ✅ Pass / ❌ Fail
- All SQL queries validated: [N/N]
- All comparisons accurate: [Yes/No]
- All metrics defensible: [Yes/No]

### Best Practices: ✅ Pass / ❌ Fail
- Uses COUNT subqueries: [Yes/No]
- No anti-patterns found: [Yes/No]
- Property naming consistent: [Yes/No]

### Tool References: ✅ Pass / ❌ Fail
- Module 1 Lesson 3 is source of truth: [Yes/No]
- Later lessons reference correctly: [Yes/No]
- No repeated mechanics: [Yes/No]

## Issues Found

### Critical Issues (Must Fix)
1. [Query syntax error in Module X Lesson Y]
2. [verify.cypher doesn't work in Module X Lesson Y]

### Moderate Issues (Should Fix)
1. [Property naming inconsistency in Module X]
2. [SQL comparison metric inaccurate in Module Y]

### Minor Issues (Nice to Fix)
1. [Could use COUNT subquery in Module X Lesson Y]
2. [LIMIT recommended for query in Module Z]

## Test Results

### Queries Tested
- Total queries: [N]
- Passed: [N]
- Failed: [N]

### Verification Files Tested
- Total challenges: [N]
- verify.cypher working: [N/N]
- solution.cypher working: [N/N]

### SQL Comparisons Validated
- Total comparisons: [N]
- Accurate: [N]
- Issues found: [N]

## Recommendations

1. [Recommendation for improvement]
2. [Recommendation for improvement]

## Ready for Publication

[✅ / ❌] Workshop is technically accurate and ready for publication.

**Issues to resolve before publication:**
- [Issue 1]
- [Issue 2]

References

CONTENT_GUIDELINES.md - Property naming, SQL comparisons
.cursor/rules/neo4j-cypher.mdc - Cypher best practices
.cursor/review-lesson-content.mdc - Technical review section
Neo4j Cypher Manual - Official documentation