opt_tax_recur#

  • Series: lecture-dp

  • File: lectures/opt_tax_recur.md

  • Audit date: 2026-08-26

  • Corpus snapshot: c30490a2f4

  • Categories audited: writing, math, code, figures, references, links, admonitions (JAX out of scope)

  • Overall score: 7.3 / 10

  • Priority: HIGH

Score breakdown#

Category

Score

One-line note

Writing

4/10

qe-writing-005 ×7; qe-writing-001 ×3; qe-writing-003 ×3, +3 more.

Math

5/10

qe-math-010 (proposed) ×3; qe-math-003 ×2; qe-math-009 ×15.

Code

8.5/10

qe-code-001 ×3.

JAX

out of scope

JAX rules target lecture-jax.

Figures

4.5/10

qe-fig-003 ×5; qe-fig-005 ×5; qe-fig-006 ×1, +2 more.

References

9/10

qe-ref-001 ×1.

Links

10/10

no mechanical violations detected.

Admonitions

10/10

no mechanical violations detected.

Issues#

Critical#

None found.

High severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 5. Lines: 1119, 1174, 1245, 1314, 1389. Example: figsize=.

  • [qe-fig-003] — No matplotlib embedded titles. Count: 5. Lines: 1127, 1175, 1250, 1316, 1395. Example: .set(title=.

  • [qe-fig-005] — Descriptive figure names for cross-referencing. Count: 5. Lines: 1101, 1173, 1233, 1302, 1368. Example: code-cell figure without mystnb figure metadata.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 15. Lines: 262, 282, 286, 351, 355, 367, 372, 504, 512, 584, …. Example: three notation collisions, each with a simpler spelling already used elsewhere in the same file. (1) Division is written three ways: {\frac{u_l}{u_c}} with decorative outer braces (262, 504, 512, 584, 589, 659, 1078), the TeX primitive {u_c(s^{t}) \over u_c(s^0)} (282, 286), and plain \frac (715, 1157). The outer braces do nothing and \over is the legacy spelling of the \frac the file already uses. (2) \rm{:} labels the four first-order conditions (351, 355, 367, 372) where a bare : renders identically - \rm is a font switch, so \rm{:} is also a misuse of it. (3) The state set is {\cal S} at 84, 820, 826, 837, 848, 858, 934 but bare S inside the very Bellman equation those constraints belong to, \sum_{s'\in S} at 810. Also at 722-726 a single equation with no alignment point is wrapped in \begin{aligned}.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 3. Lines: 484, 884, 1157. Example: non-blackboard {\rm Prob}.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 7. Lines: 214, 230, 286, 466, 745, 978, 1135. Example: the file bolds a term at its definition seven times - government policy (161), feasible allocation (164), price system (167), competitive equilibrium with distorting taxes (173), Ramsey problem (187), Ramsey allocation (234), continuation Ramsey planner (793) - and then italicises five more at exactly the same moment: primal approach (214, ‘called the primal approach’), implementability constraint (230, ‘is regarded as an’), stochastic discount factor (286, ‘what finance economists call a’), time-inconsistency (466) and state-variable degeneracy (978, ‘this implies’). Line 745 puts a third format on the same job, marking the prose word backward-looking as inline code, and 1135 uses a bold line (‘Tax smoothing’) as a section heading where the file’s other section breaks are H3s.

  • [qe-writing-008] — Remove excessive whitespace between words. Count: 106. Lines: 35, 38, 40, 46, 47, 48, 49, 51, 55, 65, …. Example: 2 spaces.

Medium severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 3. Lines: 1174, 1245, 1393. Example: the loop at 1393-1396 indents its body 35 columns to line up under zip(‘s arguments rather than four columns under for - ax.plot(...), ax.set(...) and ax.grid() all sit at the continuation indent. It runs, but the identical loop at 1123-1129 is written correctly, so the file disagrees with itself. Two smaller PEP8 points in the same cells: figsize=(10,8) at 1245 omits the space after the comma that 1119, 1174, 1314 and 1389 all include, and 1174 binds the figure to fix rather than fig (a typo that survives only because the name is never used again).

  • [qe-fig-008] — Use lw=2 for line charts. Count: 3. Lines: 1128, 1176, 1394. Example: plot() without lw=.

  • [qe-math-003] — Use square brackets for matrix notation. Count: 2. Lines: 1061, 1072. Example: matrix environment.

  • [qe-writing-001] — Use one sentence per paragraph. Count: 3. Lines: 55, 286, 654. Example: 3 sentences in one paragraph.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 3. Lines: 499, 640, 1208. Example: the same content delivered twice. (1) 499-513 re-derives what 259-271 already established: {eq}`LSA_ta` is character-for-character {eq}`LSA_taxr` and {eq}`LSA_Arro` differs from {eq}`LS101` only in writing \(\Pi(s_{t+1}|s_t)\) for \(\pi(s_{t+1}|s^t)\), so two labelled equations exist for each object and later text has to pick one. (2) 640-642 says one thing in two sentences - ‘The means that a Ramsey plan is not time consistent.’ then ‘Another way to say the same thing is that a Ramsey plan is time inconsistent.’ (3) The whole H3 ‘### Time 0 manipulation of interest rate’ (1208-1218) restates 1146-1165 with no new content - lower the \(t=0\) tax rate, raise \(c_0\), lower \(u_{c,0}\), lower the value of \(b_0\) - and 1260-1272 then says it a third time from the figure.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 3. Lines: 323, 405, 1072. Example: three places where the argument does not connect. (1) Line 323 attaches the Lagrange multiplier to the wrong equation - ‘where \(\Phi\) is a Lagrange multiplier on the implementability condition {eq}`TS_bcPV2`’ - but TS_bcPV2 (243-249) is the household’s present-value budget constraint; the implementability condition is TSs_cham1 (292-298), which is what line 495 correctly cites for the same multiplier. (2) Line 403 promises ‘time \(t=0\) quantities \(c_0\) and \(n_0\) satisfy’ and the display that follows (405-415) is written entirely in \(c\) and \(g\) with no time-0 subscripts, so it is textually identical to {eq}`TS_barg` apart from the trailing \(\Phi(u_{cc}-u_{c,\ell})b_0\) - the reader cannot tell which variables are the time-0 ones. (3) The state ordering breaks between the prose and the code: 1053-1056 enumerates the six states as \((0,g_l),(1,g_l),(2,g_l),(3,g_l),(3,g_h),(t\geq4,g_l)\) and the display at 1071-1073 puts \(0.2\) in the fifth component, but the code at 1109 is g = np.array([0.1, 0.1, 0.1, 0.2, 0.1, 0.1]) with the war in the fourth. The figure is right because sHist_h at 1114 visits index 3, but a reader checking the code against the display finds them swapped.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 2. Lines: 747, 1053. Example: the first figure appears at line 1119, so the 1,000 lines of theory carry no visual at all, and the two constructions most in need of one are both there. ‘### Intertemporal delegation’ (747-800) is a hand-off across dates - a time-0 planner passing \(x_1(s_1)\) to a time-1 continuation planner which passes \(x_2\) onward - which is a timeline with arrows and is instead carried by eight paragraphs of prose. The war example (1053-1067) has a six-node state structure whose whole point is the 0.5/0.5 branch at \(t=3\) and then a merge at \(t \geq 4\); the lecture prints the \(6\times6\) transition matrix instead of the three-line graph, and a graph would have made the state-ordering mismatch at 1072/1109 visible on sight.

Low severity#

  • [qe-fig-006] — Lowercase axis labels. Count: 1. Lines: 1254. Example: axis label Initial Government Debt.

  • [qe-ref-001] — Use correct citation style. Count: 1. Lines: 55. Example: {cite} in narrative flow: ‘of {cite}’.

Strengths#

  • The prime is defined before it is used: 553-554 states ‘where \(s'\) denotes a next period value of \(s\) and \(x'(s')\) denotes a next period value of \(x\)’, which is what makes the roughly forty primes from 550 onward (\(s'\), \(x'(s')\), \(x_{t+1}\)) unambiguous in a literature where the same mark is a transpose.

  • Every display in the sequence formulation carries a :label: and is cited where it is used, so the primal-approach chain is navigable end to end: {eq}`TS_bcr` -> {eq}`TS_bcPV2` -> {eq}`LSA_taxr`/{eq}`LS101` -> {eq}`TSs_cham1` -> {eq}`TS_chamlag` -> {eq}`eqFONCRamsey1`/{eq}`eqFONCRamsey0` -> {eq}`TS_barg`, with the recursive half doing the same through {eq}`LSA_Bellman1`, {eq}`LSARxt`, {eq}`LSAenv`, {eq}`FONCx`.

  • The four-step statement of the primal approach at 223-236 is matched by a four-step computational algorithm at 596-617 that solves the same objects in the same order, and 619-622 closes it with the exact count of equations and unknowns (‘\(3S+3\) equations for \(S\) components each of \(\vec c\), \(\vec n\), \(\vec x\) together with \(n_0, c_0\) and \(\Phi\)’).

  • The three cases in which the time-0 first-order condition collapses onto the \(t \geq 1\) one are enumerated rather than left implicit (950-955: \(b_0=0\), quasi-linear \(u_c\), or assets large enough that \(\Phi_0=0\)), and the lecture then returns to two of them at 1274-1287 to explain why the tax rate is flat at exactly two values of \(b_0\).

  • The seven inline code cells use unicode Greek for their own variables - π at 1102, τ_reset at 1307 - so the lecture scores zero qe-code-002 findings on a file that names a transition matrix, a tax rate and two utility parameters after Greek letters.

  • The four {note} blocks carry exactly the material that would otherwise interrupt the derivation: what Lucas and Stokey’s more general initial debt looks like (54-56), that many distorted competitive equilibria exist (181-183), the stochastic-discount-factor reading of \(\beta^t u_c(s^t)/u_c(s^0)\) (285-287), and the warning that utility is written over \(n\) rather than \(\ell\) to match the code (1083-1086).