Building a new learning area

The procedure for taking a MATATAG learning area from nothing to a shipped artifact set.

Ten Mathematics grades were built before this document existed, and the order in which things went wrong is the reason it does. It is written so the next area costs a fraction of what the first one did — and so that the mistakes that were expensive the first time are impossible the second.

Research on the seven unbuilt areas is at docs/research/learning-areas.md; the same facts in machine-readable form are at data/learning-areas.json. The artifact contract itself is ARTIFACT-SPEC.md and is not superseded by this document — this is the process, that is the product.

Step 0 — Obtain the curriculum guide. This is a gate, not a step.

Do not start without it. Not "start and verify later" — start.

This repository built a Grade 1–10 Mathematics spine from search summaries. It was wrong in seven of ten rows, and every wrong row was individually plausible: the right topic for that grade band, the wrong topic for that grade. Plausibility is what makes this failure mode expensive — nothing looks wrong until the guide is opened.

If the guide genuinely cannot be obtained, the honest output is a syllabus with an empty competency table and a note saying why — not a syllabus with invented competencies. The repository has shipped the former before and it was the right call.

Step 1 — Fill in the eight organizers

Every MATATAG curriculum guide is assembled from the same eight parts, defined DepEd-wide in DO 8 s. 2015 and DO 21 s. 2019 and quoted in learning-areas.md §2. A new learning area does not need a new document structure — it needs its own values for these eight.

Work through them in this order, because each constrains the next:

1. Content Domains — the strands. Are they stable across all grades? This is the single most consequential question in the whole build. Mathematics has three domains stable across ten grades, which is the only reason one template carried ten grades with a genuine vertical progression. An area whose domains change at a key stage boundary is effectively two areas and should be planned as two.
2. Key Stage Standards — one per key stage the area spans.
3. Grade Level Standards — one per grade.
4. Content Standards — per quarter.
5. Performance Standards — per quarter. These drive the assessment pack and the rubric poster.
6. Learning Competencies — the atoms. Everything learner-facing is built from exactly one.
7. Standard and Key Stage — definitional; already fixed and quoted in the research.

Record each with its CG page number. The syllabus template has a slot for every one.

Step 2 — Settle the five parameters before writing anything

Mathematics answered all five one way. No other area answers all five the same way, and each mismatch is a structural change, not a wording change. Settle them first; discovering one at artifact seven means rewriting artifacts one through six.

2.1 Which grades does the area actually cover?

From data/learning-areas.json. Only Mathematics spans 1–10. Science is 3–10, Filipino and English 2–10, AP 4–10, EPP 4–6, MAPEH 4–10, GMRC 1–6.

Check for a handover. Four strands change name mid-sequence — Language + Reading and Literacy → Filipino + English at Grade 2, Makabansa → AP at Grade 4, EPP → TLE at Grade 7, GMRC → Values Education at Grade 7. A folder named g07-epp would be wrong; it is g07-tle.

2.2 What language, and in which direction?

Mathematics has an English curriculum guide. So for Grades 1–3 the English copy quotes the competency and the Filipino copy translates it — and writing the English copy is what caught a phrase the Filipino translation had dropped.

Filipino, Araling Panlipunan and GMRC may have Filipino-language guides, which reverses the direction: the Filipino artifact quotes, the English reading copy translates. Establish this from the guide itself and record it, because ARTIFACT-SPEC.md §5 rule 1b names the English copy as "more authoritative for competency wording" — a claim that is true for Mathematics and false for a Filipino-medium area.

For Filipino and English as subjects, think before generating a language variant at all. In Mathematics both copies teach the same thing. In a language subject the language is the content, and an English reading copy of a Filipino grammar lesson may not be a coherent document. The rule "one language per artifact, never mixed" does not resolve this — it is upstream of it.

2.3 Five-day week or four?

Every lesson plan here is a five-day ILAW week and every syllabus maps 33 five-day weeks. Under the DO 12 s. 2024 flexible option, Filipino, Araling Panlipunan, EPP/TLE and MAPEH are taught four times a week (learning-areas.md §7).

A four-day week is not cosmetic. It redistributes the teaching, moves the assessment day, and changes the week count the syllabus has to cover. Decide before the syllabus, not after.

2.4 Which assessment weights?

Not uniform. Grades 4–10 under DO 015 s. 2026:

• Filipino, English, Mathematics, Science, AP, GMRC/VE → 20 / 50 / 30
• EPP/TLE and MAPEH → 20 / 60 / 20

Key Stage 1 is descriptive with no numerical grade. The weights are encoded in three artifacts — the class record, the rubric poster and the assessment pack — so getting them wrong is three rebuilds.

2.5 How many components?

Mathematics is one subject with one grade. MAPEH is two — Music and Arts, and PE and Health, separately graded and averaged. EPP/TLE has components that may rotate by quarter.

A two-component area needs two spines, two competencies per week and a class record that averages two sub-grades. Treat it as two builds sharing a folder, not one build with a wider scope.

Step 3 — Choose the spine

For each grade, pick the one competency the artifact set is built around.

What the Mathematics build learned, and would do the same way again:

• Read the competency list, not the content-standard summary. Three of the ten spine rows changed late because the guide says something narrower than the band description implies.
• Take the CG's own listing order seriously. It is the closest thing to a sequence the guide gives, and week placement was derived from it.
• The CG assigns content to quarters, never to weeks. Mapping quarter → term → week is this repository's inference and is labelled as such everywhere it appears. A school's Budget of Work would replace the guesswork; none has been obtained.
• Pick a competency a learner can be wrong about in an interesting way. The misconceptions card, the remediation sheet and the game all depend on there being a characteristic error. A competency with no interesting failure mode makes four artifacts thin.

Step 4 — Build in dependency order

Not the order they are listed in the spec. Later artifacts derive from earlier ones, and three are generated from the documents rather than written.

syllabus.md                    the whole year; everything else narrows from it
  └── lesson-plan-ilaw.md      the five-day (or four-day) week, prescribed format
        └── lesson-plan.md     day 1 at teaching depth
              ├── slides.html          what the class sees
              ├── worksheet.html       what the class holds
              │     └── worksheet-remediation.html
              ├── game.html            the interactive route to the same competency
              ├── offline-activities.md    3 individual + 2 group, chalk-only
              └── wall-chart.html → .png → .pdf
assessment.md                  TOS, papers with keys, rubrics
  ├── class-record.html        raw scores in, grade out (omit for Grade 1)
  └── parent-guide.html        the page that leaves the building

generated — never hand-edited, `node tools/cards.mjs`:
  misconceptions-card.html · observation-card.html · rubric-poster.html

On the game. Mathematics auto-checks because numeric answers are decidable. Most other areas are not, and a game that scores an undecidable answer is worse than no game. Legitimate alternatives that keep the offline-first, no-server constraint: classification and sorting, sequencing a procedure, map and timeline placement, matching, hazard-spotting, prediction with a revealed outcome. For a values area, consider whether a scored game is appropriate at all — a scenario explorer with no score may be the honest artifact.

Step 5 — Wire it in

Nothing is shipped until it is reachable. In order:

1. data/grades.json — the entry drives the portal, the gallery and the grade index. Match an existing entry's shape exactly, including facts, toc and any en variant.
2. node tools/cards.mjs — generate the three derived cards.
3. node tools/build.mjs — renders every .md to .html, builds dist/, regenerates download bundles, _headers and _redirects. New docs are picked up automatically by the markdown walk; nothing needs registering.
4. npm test — must be EXIT=0 before commit.

Step 6 — What the tests will demand

Written down because each was added after something shipped broken.

Add a guard for whatever this area does that Mathematics did not. A four-day week, a two-component grade, a Filipino-language source guide — each is a new way to be wrong, and the pattern here is that a guard is written the moment a defect is understood, not after it recurs.

Pre-flight checklist

Every line is a decision that was expensive to reverse.

• Curriculum guide committed to docs/research/source/, with extracted .txt
• Content domains listed, and their stability across grades established
• Grades the area covers confirmed; folder named for the right side of any handover
• CG language established, and the quote/translate direction recorded
• Five-day or four-day week settled
• Assessment weights settled for the key stage being built
• Component count settled — one spine or two
• Spine competency chosen per grade, from the competency list, with page numbers
• Week placement recorded as this repository's inference, not as DepEd's
• Game mechanic chosen that suits the area, or a reasoned decision to ship something else
• npm test green

The five parameters, answered per area

Everything known as of this research. Tier B/C throughout — confirm against the guide. Full reasoning per area is in learning-areas.md §10.

Read the bold cells as the places the Mathematics template will quietly do the wrong thing.

Three orderings worth knowing before you pick:

• Easiest first: Science — done, all eight grades. The guide was committed at docs/research/source/ before a line was written, so its domains, quarter map and key stage standards were Tier A from the start. Eight grades, English guide, familiar weights, five-day week, answers that auto-check. Its only new demand was the mandatory quarterly performance task, and the guide supplies the tasks.

  One thing the guide taught that no amount of searching had: the quarter-to-domain mapping changes by grade. Grades 3–6 run Materials → Living Things → Force/Motion/Energy → Earth and Space, but Grades 7–10 are a 4 × 4 Latin square, so Grade 8 opens on Life Science and Grade 9 on Force, Motion and Energy. Assuming Quarter 1 is Materials throughout is right for five grades and wrong for three.

  What the eight builds cost, for the next area's planning. The single largest piece of unplanned work was not content: it was that a grade number stopped being an identity the moment a second learning area landed. g03-math and g03-science are both "Grade 3", and the grade number was silently the key in the inventory's cell map, in the short-URL table, in the gallery's lookups and in five test assertions written as constants. All of that is now keyed on the directory slug or derived from data/grades.json, so the third learning area should not pay it again — but budget a day to find out whether anything was missed.

• Hardest: MAPEH. Two guides, two spines, two grades averaged, a movement half that cannot happen at a desk, and 60% of the mark awarded by a teacher watching.

• Most constrained by something other than the curriculum: GMRC. A statute names its pedagogy, and the honest conclusion is that its flagship artifact is the offline pack, not the screen.

What generalises, and what does not

From the ten Mathematics builds, kept here because the same pressures will apply.

Carried over without amendment: the artifact spine, the ILAW and Lesson Exemplar headings, the three-term syllabus, the offline-first constraint, the accessibility floor, print-readiness, and the one-language rule.

Did not generalise: the visual system. "Ten Times" is place-value specific and Grade 1 needed its own (DESIGN-WHOLE-AND-PARTS.md). Expect to design a visual metaphor per area, not to inherit one.

The recurring lesson, in one line: the structure travels, the content does not — and the content is where every expensive mistake has been.