How Do I "Fix" My Project?

Adapted from @alexren at hwdocs.hackclub.com

Projects get sent back for revision all the time. It's not personal. The goal is to help you build something that actually works. Here are the most common reasons and how to fix them.

1. Missing Project Files

You need to include your source files, not just exports or builds.

Software projects:

Include your actual source code, not just a built/compiled version
If you have a build step, include instructions on how to run it locally
Include a package.json, requirements.txt, or whatever dependency file your project uses
Don't commit node_modules, build folders, or .env files. Use a .gitignore

Hardware projects:

3D models: STL/OBJ/3MF files aren't enough. Include the original source (.f3d for Fusion, Onshape link, etc.) AND a .STEP file
PCBs: Include .kicad_pro, .kicad_sch, and .kicad_pcb files (or the equivalent for EasyEDA). Gerbers alone aren't enough
Firmware: Include as much code as possible, even if it can't fully run without the hardware

Source files let reviewers verify your work and help you debug issues. Export formats and compiled builds lose important information.

Don't submit a half-built app with placeholder pages and TODO comments everywhere. Your project should be functional. It doesn't need to be perfect, but the core features should work. If you have a login page, it should actually log you in. If you have a search bar, it should actually search.

Hardware

Your project needs to be complete enough that someone could actually build it. That means:

3D models should include all electronics (microcontrollers, screens, motors, batteries), not just the case. Adding every component prevents expensive assembly mistakes where things don't physically fit.
Firmware should contain your actual project logic, not basic test sketches like "blink LED" or "read sensor." Include compilation instructions so someone could build it.
Wiring diagrams should label every connection clearly. A single line connecting screenshots of parts is not a wiring diagram.

3. Poor README

Your README is the first thing reviewers see. It should explain:

What the project is and what it does
How to set it up and run it (for software: install steps, commands to run. For hardware: assembly instructions)
What components/dependencies are needed
Screenshots or photos showing what it looks like

If a reviewer can't understand your project from the README alone, it'll get sent back.

4. Bloated Parts List (Hardware)

Common issues:

Requesting overpowered parts for simple tasks
Adding "just in case" extras
Poor sourcing (paying $35 for an Arduino when you can get a compatible board for $5)
Requesting a full spool of filament for a 100g print

We're a nonprofit with limited funds. Be efficient with what you request. If there's a cheaper alternative that works, use it.

5. Lack of Polish

Polish is what turns a working prototype into a finished project.

Software: Does it have a clean UI? Are there broken links or placeholder text? Is there error handling? Could you show this to someone and they'd understand how to use it without you explaining?

Hardware: Does it have an enclosure or case? Are the edges clean? No dangling wires or exposed breadboards in the final build.

You don't need perfection, but it should look intentional.

Here's an example. The Orpheuspad before and after polish:

Before

After

The polished version has embossed patterns, a tilt angle, rounded corners, chamfers, and a logo. The same principle applies to software: a polished app has consistent styling, good error messages, and a UI that makes sense without a manual.

6. Too Much AI

AI assistance is allowed, but your submission has to be work you understand and have polished. If a reviewer flagged heavy AI usage, here's how to recover:

Rewrite AI-heavy modules by hand. Pick the parts you don't understand and write them from scratch. Reviewers can tell the difference.
Add your own polish. Error handling, edge cases, real test coverage, UI refinements. These are the things a one-shot AI prompt doesn't produce.
Rewrite the README in your voice. Explain the trade-offs you made and the parts you struggled with.
Check your journals. Journals must be written by you, not AI. If any were generated, rewrite them honestly before resubmitting.
Be able to explain every line. If a reviewer asks how a function works and you can't answer without re-asking the AI, rewrite that function.

Mark the AI-usage checkbox on your project and honestly describe what you used AI for. Reviewers care less about the fact and more about what you did with the output.

7. Plagiarism or Fraud

These will get your project permanently rejected:

Following a tutorial almost exactly 1:1 and submitting it as your own
Submitting a project built by someone else as your own
Using AI to generate your entire project without any review, polish, or iteration (AI-assisted work you understand and refine is fine; AI-generated journals are never fine)
Intentionally inflating tracked time (leaving Hackatime running while not coding, leaving timelapse running while inactive)

Plagiarism or fraud results in a permanent ban from the program and potentially Hack Club as a whole. Don't risk it.