workshop-review-technical

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:

1. Neo4j Aura Free instance (or local Neo4j)
2. Workshop data files downloaded
3. Data model imported
4. Access to Query tool

Preparation steps:

1. Create fresh Aura instance
2. Import workshop data using Data Importer
3. Verify all nodes/relationships exist
4. 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:

1. Copy query from lesson
2. Run in Query tool
3. Verify:
   • No syntax errors
   • Returns results (or appropriate empty set)
   • Results match lesson description
   • Property names correct
4. 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:

1. Test verify.cypher

   • Run in Query tool
   • Returns exactly 2 columns: outcome, reason
   • outcome is boolean
   • reason is helpful message

2. 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

3. 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

4. Test with complete data

   • Import all expected data
   • Run verify.cypher
   • outcome should be true
   • reason should confirm success

5. 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:

1. Verify SQL syntax

   • SQL query is valid
   • Would run in a relational database
   • Uses appropriate dialect (PostgreSQL, MySQL, etc.)

2. Verify equivalence

   • SQL produces same results as Cypher
   • Row counts match
   • Columns match
   • Data values match

3. Verify fairness

   • SQL is reasonable (not intentionally verbose)
   • Uses appropriate JOINs and indexes
   • Represents what a competent SQL developer would write

4. 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:

1. Read the claim:

   • "Building Block 1: Products exist in the graph ✓"

2. Verify technically:

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

3. 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
   

4. 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