[davidhbernstein]

Part of #3, which asks for a troubleshooting section for the common optimizer and boundary issues.

The thing worth fixing first

The README has had a Troubleshooting section since an earlier pass, but its first bullet still said:

sigma_u is essentially zero, with a wrong-skew warning. The OLS residuals are skewed the wrong way, and the maximum likelihood estimate is then OLS with no inefficiency.

PR #59 split that state into two opposite readings — with the skew the wrong way the boundary is the MLE, with the skew the right way the data say inefficiency is present and the fit is suspect — and updated man/sfm.Rd and NEWS.md while the README was left as it was. A reader following the README would have taken a suspect fit for the Waldman case, which is exactly the misreading #59 existed to prevent. That bullet now gives both readings and names the field that decides which applies.

The new page

man/sfa-troubleshooting.Rd, a sibling of the existing sfa-wrongskew.Rd and in the same shape — symptom first, remedy after, documentation only. It covers what the README does not have room for:

• the two readings of a boundary sigma_u, and skewness_test() as the thing to run before concluding either;
• NTN's sigma_v collapse, why the boundary is the estimate there, and why every standard error is NA rather than merely missing;
• tHN's own boundary flag, and $thn_starts$n_distinct > 1 as evidence of multimodality rather than of a bad fit;
• convergence code 99 (this package's own: the last minimizer stage returned nothing usable, so the estimates come from the stage before and the SEs are NA), and 51/52, where sfa_diagnostics() calls a non-zero line-search code benign only with a small relative gradient and a positive definite Hessian to show for it, and unverified when the fit carries no objective to check with;
• vcov(type = "bhhh") where the Hessian is singular, and why "sandwich"/"clustered" need keep_objective = TRUE;
• simulation noise in the simulated-ML models and simulation_se() as the way to quantify it;
• the psfm() estimators that maximise no likelihood, so logLik()/AIC() return NA by construction;
• the factor of two between sfm's SD link and psfm's variance link, and z_link = "var" to align them;
• the reparameterised row names, and fit$out[, "par"].

How the claims were checked

Off the code, not off the docs — the docs are what sent me here:

claim	source
code 99, its message, and the "try optHessian = FALSE, bhhh, other starts" advice	R/opts.R:195-231
51 = L-BFGS-B warning, 52 = ERROR, and the benign/unverified verdict	R/diagnostics.R:83-131
the bhhh hint and the keep_objective requirement	R/sfareg_methods.R:110-140
SSFE carries no $opt	R/psfm.R:2735
NU reports theta, not sigu	R/starting.values.R:348
maxit.bobyqa / maxit.nlminb / maxit.psoptim / maxit.optim	R/sfm.R:7-10

tools::checkRd() is clean and every \link target is an existing topic (sfa-wrongskew, sfa_diagnostics, skewness_test, efficiency_ci, simulation_se, sfareg-methods, sfm, psfm, and vcov.sfareg via its alias in sfareg-methods.Rd).

Docs only — no code paths touched, so no NEWS entry.

🤖 Generated with Claude Code