Workmanlike

Podcast 2 — In conversation

Speaker A: The particular texture of workmanlike as a critical term is worth unpacking carefully. In sports commentary — particularly cricket and football reporting — workmanlike is one of the most frequently used assessments, and understanding its precise connotation matters. A workmanlike innings in cricket is one that involves a lot of correct shot-playing, sensible running between the wickets, and grinding out runs without taking many risks. It is not elegant or entertaining, but it does the job — the batsman has fulfilled their responsibility to the team. The word acknowledges effort and correctness while declining to celebrate inspiration.

Speaker B: In the context of software and engineering work, workmanlike has a precise and useful meaning. A workmanlike solution to a technical problem is one that is correctly implemented, properly tested, handles edge cases, is reasonably efficient, and is documented clearly enough for others to maintain. It is everything that a professional solution should be. It may not be architecturally elegant or algorithmically clever, but it works reliably and predictably. In most professional contexts, workmanlike is exactly the right goal — brilliant and inspired solutions are rarer and less reliable than solid, workmanlike ones.

Speaker A: Workmanlike versus professional — what is the distinction?

Speaker B: Professional describes an approach that meets the expected standards of a profession — it implies adherence to norms, ethics, and quality expectations. Workmanlike is more specifically about the execution quality — the practical skill and thoroughness of the work itself. A professional might produce workmanlike work, but professional can also describe manner, attitude, and ethics, while workmanlike is specifically about the quality and craft of the output. Professional is the broader quality; workmanlike is the specific execution descriptor that occupies the competent-but-not-inspired space on the quality scale.

Speaker A: What is a common mistake about workmanlike?

Speaker B: Using it purely as a compliment when it also contains a mild reservation. If you tell a writer that their book is workmanlike and expect them to be pleased, you may be surprised to find that they feel slightly damned with faint praise. The word's implied reservation — not inspired, not exceptional, competent but no more — is present even when the word is used positively. Understanding this dual quality is essential for using the word accurately and for understanding what is being communicated when you hear it applied to your own work or performance.

Speaker A: Any close synonyms?

Speaker B: Competent is close and shares the implied limitation — competent is not the same as exceptional. Proficient is close — skilled and capable without necessarily being brilliant. Solid is close — reliable and sound, without being spectacular. Dependable is close — you can count on it, even if it does not dazzle. Serviceable is close — it will serve the purpose adequately. Adequate is weaker — it merely meets the minimum. Meticulous is close in implying thoroughness but without the implied limitation. Accomplished is stronger — it implies a higher level of achievement. Workmanlike occupies its own specific space: more than adequate, less than exceptional, defined by the craft ethic of the skilled tradesperson.

Podcast 3 — Prompt engineering

Speaker B: Welcome to the workshop. Today we prompt AI using the word workmanlike — building the code quality and engineering standards systems, professional deliverable assessment tools, software craftsmanship and best-practice enforcement platforms, peer review and code quality measurement systems, and technical writing and documentation quality tools that ensure all work meets a solid, professional, workmanlike standard.

Speaker A: So workmanlike tells the AI to build the engineering quality and standards systems — the code quality tools that ensure code is workmanlike — correct, tested, documented, and maintainable — rather than brilliant but brittle or clever but opaque, the professional deliverable assessment frameworks that measure whether work meets the competent and thorough standard that workmanlike implies, and the technical standards enforcement tools that keep all work above the professional baseline?

Speaker B: Exactly. It signals engineering quality standards, code craftsmanship, and professional deliverable assessment. Let me start with a code quality and engineering standards enforcement system.

Build a code quality and engineering standards enforcement system: define a set of quality standards — test coverage minimums, documentation requirements, complexity limits, security scanning passing, and code style compliance. Automatically check every pull request against these standards before merging. Report which standards pass and which fail, with specific failing items and their locations. Require all standards to pass before merge is permitted. Track quality trends over time — is the codebase becoming more or less workmanlike? Generate weekly code quality reports for the engineering team.

Speaker B: Code quality system defines test-coverage-documentation-complexity-security-style standards, auto-checks every pull request, reports pass-fail with specific failing items and locations, requires all-pass before merge, tracks quality trends over time, and generates weekly engineering quality reports — the AI builds the standard definer, the PR checker, the reporter, the merge gate, the trend tracker, and the report generator.

Speaker A: Requiring all standards to pass before merge is permitted — making the quality gate a hard block rather than a soft warning — is the baseline maintenance mechanism: a soft warning that can be ignored will be ignored, especially under time pressure; a hard gate that blocks the merge ensures that the quality baseline is maintained consistently, because merging code that fails the standards becomes impossible rather than merely discouraged.

Speaker B: Hard merge gate as the soft-warning-ignored-under-pressure versus impossible-to-bypass baseline maintenance mechanism. Now the quality standards schema.

Design a code quality standards and measurement schema: a quality_standards table recording each defined standard with an ID, the standard name, the category as testing, documentation, complexity, security, or style, the threshold or requirement, the enforcement level as required or advisory, and whether it applies to all repositories or specific ones. A quality_checks table recording each automated check run with the standard ID, the repository and pull request reference, the check timestamp, the measured value, the threshold, and a pass or fail result. A quality_trends table recording weekly per-repository quality snapshots with the repository ID, the week date, and the score for each standard category. A quality_gate_view computing per-pull-request the overall gate result — pass or fail — and the list of failed standards.

Speaker B: Quality standards schema stores standards with category-threshold-enforcement-scope, checks with repository-PR-timestamp-measured-threshold-result, weekly repository quality snapshots, and a gate view with per-PR overall-result and failed-standards list — the AI builds the four-table schema.

Speaker A: The weekly quality snapshot per repository — recording the quality scores for each standard category over time — is the codebase trend mechanism: a single PR check shows the quality of one change; weekly snapshots show whether the overall codebase quality is improving or degrading over time; a codebase whose test coverage has dropped from eighty percent to sixty-five percent over six months is trending away from workmanlike toward risky.

Speaker B: Weekly snapshot trends as the single-PR-state versus improving-or-degrading-over-time codebase trend mechanism. Next, the quality assessment interface.

Design a code quality and engineering standards dashboard for an engineering team: show each repository with a quality score card displaying scores for each standard category — testing, documentation, complexity, security, and style. Colour-code categories green for meeting standards, amber for approaching threshold, and red for failing. Display a pull request quality gate status panel showing recently merged and pending PRs with their gate results. Show a quality trend chart for each repository over the last three months. Allow drilling down to see specific failed standards for any PR or repository.

Speaker B: Quality dashboard shows per-repository green-amber-red category score cards, PR quality gate status with recently-merged-and-pending results, three-month quality trend chart per repository, and drill-down to specific failed standards for any PR or repository — the AI builds the score cards, the category coder, the gate status panel, the trend chart, and the drill-down.

Speaker A: The three-month quality trend chart per repository — visualising quality category scores over time — is the engineering health narrative: a score card shows current state; the trend chart shows the story behind the current state; a repository with a currently low test coverage score that has been improving for three months tells a different story than one with the same score that has been declining; the trend is the engineering team's quality narrative.

Speaker B: Three-month trend as the current-state-only versus improving-or-declining narrative engineering health story mechanism. On to peer review quality.

Create a structured peer code review and quality assessment system: define a code review rubric with specific dimensions — correctness, testability, readability, maintainability, security, and performance considerations. Guide reviewers through each dimension with specific questions to evaluate. Score each dimension. Generate a structured review report. Track review quality — do different reviewers produce consistent assessments? Alert when code receives a low score in any dimension. Archive review reports for each pull request as part of the engineering record.

Speaker B: Peer review system defines correctness-testability-readability-maintainability-security-performance rubric dimensions, guides reviewers through dimension-specific questions, scores each dimension, generates structured reports, tracks inter-reviewer consistency, alerts on low-dimension scores, and archives reports as engineering records — the AI builds the rubric, the review guide, the scorer, the report generator, the consistency tracker, and the archiver.

Speaker A: Tracking inter-reviewer consistency — measuring whether different reviewers produce similar assessments of the same code — is the review quality calibration mechanism: a code review process where one reviewer consistently gives high marks and another consistently gives low marks for similar code is not measuring code quality; it is measuring reviewer bias; consistency tracking identifies these divergences and enables calibration discussions that align the team's quality standards.

Speaker B: Inter-reviewer consistency as the reviewer-bias-not-code-quality versus aligned-standards calibration mechanism. Now something whole.

Build an engineering quality and craftsmanship management platform for a software organisation: define and enforce quality standards across all teams and repositories. Track code quality trends at repository, team, and organisation level. Manage structured peer review processes. Measure and improve documentation quality. Identify repositories and teams with consistently workmanlike output and share their practices as organisation-wide standards. Generate quarterly engineering quality reports for technology leadership.

Speaker B: Engineering quality platform enforces standards across all teams-and-repositories, tracks quality trends at repository-team-organisation levels, manages structured peer review, measures documentation quality, identifies workmanlike-standard repositories for practice sharing, and generates quarterly leadership quality reports — the AI builds the full engineering quality and craftsmanship management platform.

Speaker A: Identifying repositories and teams with consistently workmanlike output and sharing their practices as organisation-wide standards — learning from the consistently solid performers rather than only from exceptional ones — is the baseline excellence dissemination mechanism: the most consistently workmanlike teams may not produce the most spectacular code, but they produce the most reliably good code; their practices — rigorous testing, clear documentation, consistent code review — are the ones most worth spreading.

Speaker B: Workmanlike-standard practice sharing as the spectacular-rare versus consistently-solid-practice-spreading baseline excellence dissemination mechanism. Last one — quality API.

Write a code quality standards and pull request gate REST API: provide endpoints for querying all defined quality standards with their thresholds and enforcement levels, submitting a quality check result for a pull request with the measured values for each standard, querying the current gate status for a pull request — which standards pass and which fail, querying the quality trend for a repository over a specified time period, and retrieving the quality score breakdown for any merged pull request from the archive. Return all results as structured JSON with pass-fail flags and measured values.

Speaker B: Quality standards API provides standard definitions with thresholds-enforcement, PR quality check submission with measured values, PR gate-status queries with pass-fail standards, repository quality trend queries, archived PR quality score retrieval, and structured JSON with pass-fail flags and values — the AI builds the full code quality standards and pull request gate REST API.

Speaker A: Archived pull request quality scores — retrieving the quality assessment for any previously merged PR — is the retrospective analysis foundation: a team that wants to understand when and why quality declined can query the archives for specific PRs and identify the changes that introduced quality regressions; the archive converts real-time quality checking into a historical record that supports root-cause analysis.

Speaker B: That is the goal — one craftsmanship adjective, better-designed code quality standards and engineering craftsmanship systems. Keep it in your kit.