Break the First Build and Trace the Failure

You learn a build system faster when you see it fail on purpose.

The rule is simple:

Make one bounded change, predict the failure, observe evidence, repair it, then verify recovery.

Do not create five errors at once.

That destroys the evidence chain.

Failure A: wrong directory

Run a Jekyll command from a directory that is not your project root.

Observe the result.

What evidence tells you Jekyll cannot find the expected project/dependency context?

Return to the project root and verify recovery.

Failure B: dependency context

Without deleting anything, compare the behavior of the project-specific command you normally use with an intentionally incomplete invocation if your environment allows it.

The point is not to vandalize Ruby.

The point is to recognize that the executable/dependency layer can fail before Jekyll processes page source.

Failure C: source mistake

Make one small, recoverable source error.

For example, add a malformed front-matter block only if you have already introduced front matter in your environment, or create a clearly invalid configuration in a disposable copy.

If Unit 1 has not introduced that syntax yet, use a safer HTML/content mistake and observe whether Jekyll itself fails or the browser merely renders unexpected markup.

That difference is valuable:

Not every bad page appearance is a build failure.

Failure D: stop the server

1. Start bundle exec jekyll serve.
2. Confirm the browser can load the site.
3. Stop the server with the normal terminal interrupt.
4. Refresh.

The source did not disappear.

The generated files did not necessarily disappear.

The delivery process stopped.

Build a failure record

For one experiment, record:

Change I made:
Prediction:
Observed terminal evidence:
Observed generated-output evidence:
Observed browser evidence:
Layer responsible:
Repair:
Verification after repair:

Avoid the reset-everything habit

Rebooting or reinstalling can sometimes make a symptom disappear.

It can also erase the evidence that would have taught you what happened.

Before using a broad reset, ask:

1. What do I already know works?
2. What is the narrowest failed boundary?
3. What evidence would discriminate between two likely causes?

That habit will matter much more than memorizing Jekyll commands.

Checkpoint

Defend one bounded claim:

The failure was in __________, not __________, because __________ still worked and __________ evidence failed.

If your claim says "Jekyll was broken," it is too broad.